MarkLogic Server 11.0 Product Documentation

Application Developer's Guide — Chapter 2

Configuring Your Database

MarkLogic Server automatically creates an empty schema database, named Schemas, at installation time.

Every document database that is created references both a schema database and a security database. By default, when a new database is created, it automatically references Schemas as its schema database. In most cases, this default configuration (shown in the following figure) will be correct:

In other cases, it may be desirable to configure your database to reference a different schema database. It may be necessary, for example, to be able to have two different databases reference different versions of the same schema using a common schema name. In these situations, simply select the database from the drop-down schema database menu that you want to use in place of the default Schemas database. Any database in the system can be used as a schema database.

In select cases, it may be efficient to configure your database to reference itself as the schema database. This is a perfectly acceptable configuration which can be set up through the same drop-down menu. In these situations, a single database stores both content and schema relevant to a set of applications.

To create a database that references itself as its schema database, you must first create the database in a configuration that references the default Schemas database. Once the new database has been created, you can change its schema database configuration to point to itself using the drop-down menu.

Loading Your Schema

HTTP and XDBC Servers connect to document databases. Document insertion operations conducted through those HTTP and XDBC Servers (using xdmp:document-load, xdmp:document-insert and the various XDBC document insertion methods) insert documents into the document databases connected to those servers.

This makes loading schemas slightly tricky. Because the system looks in the schema database referenced by the current document database when requesting schema documents, you need to make sure that the schema documents are loaded into the current database's schema database rather than into the current document database.

There are several ways to accomplish this:

1. You can use the Admin Interface's load utility to load schema documents directly into a schema database. Go to the Database screen for the schema database into which you want to load documents. Select the load tab at top-right and proceed to load your schema as you would load any other document.
2. You can create an XQuery program that uses the xdmp:eval built-in function, specifying the <database> option to load a schema directly into the current database's schema database:

   xdmp:eval('xdmp:document-load("sample.xsd")', (),
           <options xmlns="xdmp:eval">
               <database>{xdmp:schema-database()}</database>
           </options>)

3. You can create an XDBC or HTTP Server that directly references the schema database in question as its document database, and then use any document insertion function to load one or more schemas into that schema database. This approach is not necessary.
4. You can create a WebDAV Server that references the Schemas database and then drag-and-drop schema documents in using a WebDAV client.

Referencing Your Schema

Schemas are automatically invoked by the server when loading documents (for conducting content repair) and when evaluating queries (for proper data typing). For any given document, the server looks for a matching schema in the schema database referenced by the current document database.

1. If a schema with a matching target namespace is not found, a schema is not used in processing the document.
2. If one matching schema is found, that schema is used for processing the document.
3. If there are more than one matching schema in the schema database, a schema is selected based on the precedence rules in the order listed:
   1. If the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute of the document root element specifies a URI, the schema with the specified URI is used.
   2. If there is an import schema prolog expression with a matching target namespace, the schema with the specified URI is used. Note that if the target namespace of the import schema expression and that of the schema document referenced by that expression do not match, the import schema expression is not applied.
   3. If there is a schema with a matching namespace configured within the current HTTP or XDBC Server's Schema panel, that schema is used. Note that if the target namespace specified in the configuration panel does not match the target namespace of the schema document, the Admin Interface schema configuration information is not used.
   4. If none of these rules apply, the server uses the first schema that it finds. Given that document ordering within the database is not defined, this is not generally a predictable selection mechanism, and is not recommended.

Working With Your Schema

It is sometimes useful to be able to explicitly read a schema from the database, either to return it to the outside world or to drive certain schema-driven query processing activities.

Schemas are treated just like any other document by the system. They can be inserted, read, updated and deleted just like any other document. The difference is that schemas are usually stored in a secondary schema database, not in the document database itself.

The most common activity developers want to carry out with schema is to read them. There are two approaches to fetching a schema from the server explicitly:

1. You can create an XQuery that uses xdmp:eval with the <database> option to read a schema directly from the current database's schema database. For example, the following expression will return the schema document loaded in the code example given above:

   xdmp:eval('doc("sample.xsd")', (), 
     <options xmlns="xdmp:eval">
       <database>{xdmp:schema-database()}</database>
     </options>)

   The use of the xdmp:schema-database built-in function ensures that the sample.xsd document is read from the current database's schema database.

2. You can create an XDBC or HTTP Server that directly references the schema database in question as its document database, and then submit any XQuery as appropriate to read, analyze, update or otherwise work with the schemas stored in that schema database. This approach is not necessary in most instances.

Validating XML and JSON Data Against a Schema

This section describes two ways to validate your schemas:

• Validating Schemas using Schematron
• Validating Schemas using the XQuery validate Expression
• Validating JSON Documents against JSON Schemas

xquery version "1.0-ml";

(: 
   this will validate against the schema if it is in scope, but
   will validate it without a schema if there is no in-scope schema
:)
let $node := xdmp:document-get("c:/tmp/test.xml")
return
try { xdmp:document-insert("/my-valid-document.xml", 
        validate lax { $node } ) 
    }
catch ($e) { "Validation failed: ",
             $e/error:format-string/text() } 

xquery version "1.0-ml";
import schema "my-schema" at "/schemas/my-schema.xsd";

(: 
   this will validate against the specified schema, and will fail
   if the schema does not exist (or if it is not valid according to
   the schema)
:)
let $node := xdmp:document-get("c:/tmp/test.xml")
return
try { xdmp:document-insert("/my-valid-document.xml", 
        validate strict { $node } ) 
    }
catch ($e) { "Validation failed: ",
             $e/error:format-string/text() } 

{
  "language": "zxx",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "count": { "type":"integer", "minimum":0 },
    "items": { "type":"array", 
               "items": {"type":"string", "minLength":1 } }
  }
}

xdmp:json-validate(
  object-node{ "count": 3, "items": array-node{12} },
  "/schemas/example.json" )

xdmp:json-validate-node(
  object-node{ "count": 3, "items": array-node{12} }, 
  object-node{
    "properties": object-node{
    "count": object-node{ "type":"integer", "minimum":0 },
    "items": object-node{ "type":"array", 
       "items": object-node{"type":"string", "minLength":1 } 
             }
    }
  }
)