PhoenixmlDb.XQuery

ISchemaProvider

Provides schema awareness to the XQuery and XSLT engines. Public extension point — callers can substitute their own implementation (RelaxNG, Schematron-derived, in-memory, dynamic) by passing it to the constructor.

#ISchemaProvider

Namespace: PhoenixmlDb.XQuery

Provides schema awareness to the XQuery and XSLT engines. Public extension point — callers can substitute their own implementation (RelaxNG, Schematron-derived, in-memory, dynamic) by passing it to the

constructor.

The default implementation, XsdSchemaProvider, ships in this package and is registered automatically by QueryEngine. Together they provide the XQuery 3.1 "Schema-Aware Conformance" features:

• validate expressions (validate strict { ... })

• schema-element() and schema-attribute() type tests

• import schema prolog declarations

• Typed node annotations (elements/attributes annotated with their XSD type)

• Full XSD type hierarchy for instance of and treat as

Implement this interface to back schema processing with a non-XSD schema language, an in-memory schema, or a custom resolution strategy. The engine calls in at compile time (for static type checks) and at execution time (for validation and type annotation).

Passing null for schemaProvider opts out of schema features entirely — every schema-element/attribute reference becomes XPST0008 and every validate raises XQDY0027. This is rare; intended for size-constrained embedded scenarios.

#Example

// Default — XsdSchemaProvider auto-registered, no schemas loaded yet.
var engine = new QueryEngine(nodeProvider: store, documentResolver: store);

// Pre-load schemas via the default provider:
var xsd = new XsdSchemaProvider("catalog.xsd");
var engine2 = new QueryEngine(nodeProvider: store, documentResolver: store, schemaProvider: xsd);

// Custom implementation:
var engine3 = new QueryEngine(nodeProvider: store, documentResolver: store, schemaProvider: new MyRelaxNgProvider());
            

#Methods

#AddSchemaText(String,String,Uri,PhoenixmlDb.XQuery.Security.ResourcePolicy)

Adds a schema given as text, for a schema written inline (XSLT's

xsl:import-schema

with an

xs:schema

child) or one the host holds in memory.

Parameters:

• targetNamespace — The namespace the schema must declare; empty for none.

• schemaText — The schema document.

• baseUri — Where the text is from, for resolving a relative schemaLocation in it; null when it has no location, and such a reference then fails.

• policy — Checked for import access for every document the text refers to; null for no restriction.

Exceptions:

• SchemaException — The schema cannot be loaded (XQST0059).

• NotSupportedException — The default: this provider takes no schema text.

#AddSchemaText(String,String,Uri,PhoenixmlDb.XQuery.Security.ResourcePolicy,Uri)

for a schema that a module holds:

is the URI that module was loaded at, passed to the host's resolver with each document the text refers to.

#GetAttributeType(PhoenixmlDb.Xdm.XdmQName)

Returns the declared type name for a global attribute declaration.

Parameters:

• name — The attribute QName.

Returns: The XSD type name, or null if the attribute is not declared.

#GetAttributeType(String,String)

String-URI overload of

.

#GetElementType(PhoenixmlDb.Xdm.XdmQName)

Returns the declared type name for a global element declaration.

Parameters:

• name — The element QName.

Returns: The XSD type name, or null if the element is not declared.

#GetElementType(String,String)

String-URI overload of

.

#GetSchemaListItems(String,String,String)

The items a lexical value has as an instance of a schema-defined LIST type: one per token, each as the list's item type. Null when the type is not a list this provider can build items for (the caller then keeps the lexical form). The value is assumed valid.

#GetSchemaSimpleType(String,String)

Describes a simple type declared by an imported schema, for matching a value against it as a SequenceType item type (

instance of

,

typeswitch

, function signatures). Null when no imported schema declares a simple type of that name.

#GetSchemaSimpleTypeNames(String)

The local names of the global simple types imported schemas declare in a namespace. Each has a constructor function of the same name (XQuery 3.1 §3.18.4). Empty by default.

#HasAttributeDeclaration(PhoenixmlDb.Xdm.XdmQName)

Checks whether a global attribute declaration exists in the in-scope schema definitions, corresponding to the

schema-attribute(Name)

type test.

Parameters:

• name — The attribute QName to look up.

Returns: true if the attribute is declared in a loaded schema.

#HasAttributeDeclaration(String,String)

String-URI overload of

.

#HasElementDeclaration(PhoenixmlDb.Xdm.XdmQName)

Checks whether a global element declaration exists in the in-scope schema definitions, corresponding to the

schema-element(Name)

type test.

Parameters:

• name — The element QName to look up.

Returns: true if the element is declared in a loaded schema.

#HasElementDeclaration(String,String)

String-URI overload of

. Preferred when the caller has the namespace URI directly (rather than going through a

), since

is not always reversible to a URI.

#HasIdrefTypedValue(PhoenixmlDb.Xdm.XdmTypeName,String)

Whether a node annotated with the schema type

and holding

has a typed value that contains an xs:IDREF, which gives the node the is-idrefs property fn:idref looks for (XDM 3.1 §5.6). True for a type derived from xs:IDREF or xs:IDREFS, and for a list or union type when one of the values validates as an IDREF. The default knows no schema types and answers false.

#HasSchemaType(String,String)

Whether an imported schema declares a global type (simple or complex) of this name.

#ImportSchema(String,Collections.Generic.IReadOnlyList<String>)

Imports a schema namespace, corresponding to the XQuery

import schema

declaration.

Parameters:

• targetNamespace — The target namespace of the schema to import. An empty string represents the no-namespace schema.

• locationHints — Optional location hints (URIs) for the schema document(s), from the at clause.

Exceptions:

• SchemaException — Thrown if the schema cannot be loaded or contains errors (maps to XQST0059).

#ImportSchema(String,Collections.Generic.IReadOnlyList<String>,PhoenixmlDb.XQuery.Security.ResourcePolicy)

under a resource policy: the location hints have already been authorised, and every further document the schema pulls in (

xs:include

,

xs:import

,

xs:redefine

) must be checked against

for import access. The default ignores the policy, so a custom provider that fetches such documents must override this.

#ImportSchema(String,Collections.Generic.IReadOnlyList<String>,PhoenixmlDb.XQuery.Security.ResourcePolicy,Uri)

for an import that a module makes:

is the URI the stylesheet or query module that holds the import was loaded at, or null when not known. A provider that asks the host's resolver for the schema documents passes it on as

. The default takes no notice of it.

#IsSchemaSimpleTypeDerivedFrom(String,String,String,String)

Whether the schema-defined simple type

is derived, in one step or several, from the schema-defined type

. False for a type and itself, and by default.

#IsSubtypeOf(PhoenixmlDb.Xdm.XdmTypeName,PhoenixmlDb.Xdm.XdmTypeName)

Determines whether

is a subtype of

in the XSD type derivation hierarchy.

Parameters:

• actualType — The type to check.

• requiredType — The type to check against.

Returns: true if actualType is equal to or derived from requiredType.

This is the core type subsumption check used by

instance of

,

treat as

, and function argument coercion. The implementation must cover the full XSD 1.1 type hierarchy including built-in types, restriction, extension, union, and list derivation.

#LimitPatternMatchTime(TimeSpan)

Asks the provider to let no single match of a schema

pattern

facet run longer than

, if it does not already hold a tighter limit. The engine calls this for a query that runs with

. The default does nothing, so a custom provider that matches patterns must override it to be covered by that limit.

#MatchesSchemaAttribute(PhoenixmlDb.Xdm.Nodes.XdmAttribute,PhoenixmlDb.Xdm.XdmQName)

Checks whether an attribute matches a

schema-attribute(Name)

test. An attribute matches if it has the declared name and its type annotation is the declared type or a subtype.

Parameters:

• attribute — The attribute node to test.

• declarationName — The attribute declaration name from the schema-attribute() test.

Returns: true if the attribute matches the schema-attribute() test.

#MatchesSchemaAttribute(PhoenixmlDb.Xdm.Nodes.XdmAttribute,String,String)

String-URI overload of

.

#MatchesSchemaAttribute(String,String,PhoenixmlDb.Xdm.XdmTypeName,String,String)

Whether an attribute with this expanded name and type annotation matches

schema-attribute(declaration)

. Names are compared by URI.

#MatchesSchemaElement(PhoenixmlDb.Xdm.Nodes.XdmElement,PhoenixmlDb.Xdm.XdmQName)

Checks whether an element matches a

schema-element(Name)

test. An element matches if it has the same name as the declaration (or a name in its substitution group) and its type annotation is the declared type or a subtype.

Parameters:

• element — The element node to test.

• declarationName — The element declaration name from the schema-element() test.

Returns: true if the element matches the schema-element() test.

#MatchesSchemaElement(PhoenixmlDb.Xdm.Nodes.XdmElement,String,String)

String-URI overload of

.

#MatchesSchemaElement(String,String,PhoenixmlDb.Xdm.XdmTypeName,String,String)

Whether an element with this expanded name and type annotation matches

schema-element(declaration)

: it has the declaration's name or substitutes for it, and its type annotation is the declared type or derived from it. Names are compared by URI: a node's

belongs to its store and means nothing to the provider.

#TryCastToSchemaSimpleType(String,String,String,Func<String,String>)

Casts a lexical value to a SCHEMA-DEFINED simple type, for

cast as

/

castable as

against a type an imported schema declares rather than a built-in XSD type.

for a namespace-sensitive type (one derived from xs:QName or xs:NOTATION), whose lexical form has a prefix to resolve against

. The default ignores the resolver.

Returns: true if the schema declares localName in namespaceUri as a simple type AND the lexical value satisfies it (including every facet — pattern, enumeration, length, bounds). false if the value does not satisfy the type. Throws only if the TYPE ITSELF is unusable — absent, or complex rather than simple — because "no such type" is a static error (XPST0051) while "value does not match" is an ordinary castable=false.

Kept on the provider rather than in the engine because facet validation is precisely what an XSD implementation already does; the engine has no facet machinery and should not grow one.

#Validate(PhoenixmlDb.Xdm.Nodes.XdmNode,PhoenixmlDb.XQuery.INodeProvider,PhoenixmlDb.XQuery.ValidationMode,String,String)

Validates a node tree against the loaded schemas, serializing it WITH its markup — child elements, attributes, text — through

, which is what resolves a node's children. The

validate

expression takes this route.

The overload without a provider cannot reach a node's children, and validated an element's start tag wrapped around its string value instead, so a schema requiring a child element rejected a valid instance and structure constraints were never checked (#40). The default implementation serializes the node and hands it to

, returning the node unchanged; implementations may override to return an annotated copy.

#Validate(PhoenixmlDb.Xdm.Nodes.XdmNode,PhoenixmlDb.XQuery.ValidationMode,String,String)

Validates a node tree against the loaded schemas, corresponding to the

validate

expression.

Parameters:

• node — The document or element node to validate.

• mode — The validation mode (strict, lax, or type).

• typeNamespaceUri — For ValidationMode.Type, the namespace URI of the target type. Null for strict and lax modes.

• typeLocalName — For ValidationMode.Type, the local name of the target type. Null for strict and lax modes.

Returns: A validated copy of the node tree with type annotations applied.

Exceptions:

• SchemaValidationException — Thrown if validation fails (maps to XQDY0027 for strict/lax, XQDY0027 for type).

Returns a deep copy of the input node tree with XdmElement.TypeAnnotation and XdmAttribute.TypeAnnotation populated from the schema. The original node tree is not modified.

The validation mode determines behavior:

• ValidationMode.Strict — the element must have a global declaration.

• ValidationMode.Lax — validate if a declaration exists, pass through if not.

• ValidationMode.Type — validate against a specific named type.

#ValidateAndAnnotate(String,PhoenixmlDb.XQuery.INodeBuilder,PhoenixmlDb.XQuery.ValidationMode,String,String)

Validates an XML string against the loaded schemas AND returns a freshly built XDM tree whose elements and attributes carry

/

populated from the schema.

Parameters:

• xmlContent — The XML markup to validate and annotate.

• builder — Node store / ID allocator the resulting tree is registered in.

• mode — Validation mode (strict, lax, or type).

• typeNamespaceUri — Optional namespace URI for type-mode validation.

• typeLocalName — Optional local name for type-mode validation.

Returns: The annotated document node, or null if annotation is unsupported.

Exceptions:

• SchemaValidationException — Thrown if validation fails (XQDY0027).

The new tree is registered in builder so it participates in the caller's node store and namespace interning. Returns null when the provider doesn't support an annotating parse — the caller should then fall back to the unannotated original node from the validate expression body.

The default implementation returns null. Built-in providers (e.g. XsdSchemaProvider) override to drive a schema-validating XmlReader through XmlDocumentParser.Parse(reader, uri, schemas), which populates XdmElement.TypeAnnotation from SchemaInfo.SchemaType.

#ValidateElementAndAnnotate(String,PhoenixmlDb.XQuery.INodeBuilder,PhoenixmlDb.XQuery.ValidationMode,String,String)

for the validation of an element, as opposed to a document: the constraints on a document as a whole are not applied, so the same ID twice, or an IDREF to no ID, in the element does not make it invalid (XQuery 3.1 §3.21.2, XSLT 3.0 §25.4.1). The default applies them, as

does.

#ValidateXml(String,PhoenixmlDb.XQuery.ValidationMode,String,String)

Validates already-serialized XML content against the loaded schemas. Convenience overload for callers (notably

xsl:result-document

) that have a string in hand rather than an in-memory XDM tree. Throws

(XQDY0027) on validation failure. Default implementation parses the content and delegates to the node-based

via a minimal XdmNode adapter; implementations are encouraged to override with a more direct path.

#ValidateXmlFragment(String,PhoenixmlDb.XQuery.ValidationMode,String,String,Collections.Generic.IReadOnlyDictionary<String,String>)

Fragment-mode counterpart of

. Validates an XML fragment (single element or sequence of nodes — not a complete document) against the loaded schemas. Used by XSLT for per-element / per-attribute / per-copy validation where no surrounding document declaration exists. Default falls back to

.

Parameters:

• xmlFragment — The XML fragment to validate.

• mode — Validation mode.

• typeNamespaceUri — Optional namespace URI for type-mode validation.

• typeLocalName — Optional local name for type-mode validation.

• inScopeNamespaces — Optional prefix→URI bindings that should be visible to the fragment without being explicitly declared inside it. Required when the fragment uses prefixed names whose declarations live on an enclosing element that the caller cannot include in the fragment text.

#See also

• XsdSchemaProvider

• QueryEngine

• IDocumentResolver