Author a custom contract schema

Define a custom schema when your contract needs a domain-specific XML vocabulary. Use the existing token, payment, and state-machine schemas when they already express the required behavior. This example adds an Acknowledgement element with a required positive policyVersion. It describes contract data. An XSD does not install executable behavior or create a new Agent API operation.

1. Choose a namespace and version

Download Acknowledgement-v1.xsd. The file uses a reserved example address:

https://schemas.example.com/neuro/Acknowledgement-v1.xsd

This address is a placeholder, not a published schema service. It works locally because you supply an explicit namespace-to-file map. Before provider submission, use a versioned namespace you control and the resolution method accepted by your provider. Unlike an upstream namespace, which you must preserve, this example’s custom namespace is yours to replace. Change it consistently in the XSD’s targetNamespace, the contract element’s xmlns, and your local map.

2. Define the allowed XML

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="https://schemas.example.com/neuro/Acknowledgement-v1.xsd"
           elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:element name="Acknowledgement">
    <xs:complexType>
      <xs:attribute name="policyVersion" type="xs:positiveInteger" use="required" />
    </xs:complexType>
  </xs:element>
</xs:schema>

The declaration allows one global Acknowledgement element. Its policyVersion attribute is required and must be a positive integer. It permits neither child elements nor additional attributes. elementFormDefault="qualified" places locally declared elements in this namespace. attributeFormDefault="unqualified" leaves ordinary attributes without a namespace. The XSD itself uses the standard XML Schema namespace, separate from your contract vocabulary. For more complex structures, use xs:sequence for ordered children, minOccurs/maxOccurs for cardinality, and explicit types for values. Add xs:import when a dependency belongs to another namespace. Load that dependency in your local schema set too, so validation can resolve it offline.

3. Embed the element in a complete contract

Download custom-acknowledgement.xml. It extends the acknowledgement tutorial with custom machine-readable data:

<Acknowledgement xmlns="https://schemas.example.com/neuro/Acknowledgement-v1.xsd"
                 policyVersion="1" />

The rest of the contract still uses urn:nf:iot:leg:sc:1.0. Its human-readable terms also name policy version 1.

Complete custom-schema contract

<?xml version="1.0" encoding="utf-8"?>
<contract xmlns="urn:nf:iot:leg:sc:1.0"
          canActAsTemplate="true" visibility="CreatorAndParts"
          duration="P1M" archiveReq="P1M" archiveOpt="P1M">
  <Acknowledgement xmlns="https://schemas.example.com/neuro/Acknowledgement-v1.xsd" policyVersion="1" />
  <role name="Participant" minCount="1" maxCount="1">
    <description xml:lang="en"><paragraph><text>The participant acknowledging the stated subject.</text></paragraph></description>
  </role>
  <parts><templateOnly /></parts>
  <parameters>
    <stringParameter name="Subject" minLength="1" maxLength="120">
      <description xml:lang="en"><paragraph><text>The subject the participant will review.</text></paragraph></description>
    </stringParameter>
  </parameters>
  <humanReadableText xml:lang="en">
    <paragraph><text>Under policy version 1, the participant acknowledges reviewing: </text><parameter name="Subject" /><text>.</text></paragraph>
    <paragraph><text>This demonstration records an acknowledgement under policy version 1. The custom machine-readable element declares data; it does not define a payment or token action. The instance lasts one month, followed by one month of required archival and one month of optional archival.</text></paragraph>
  </humanReadableText>
</contract>

policyVersion is a static value in this template. Defining a contract parameter with the same name would not establish a substitution rule in your custom vocabulary. Use a documented parameter-reference mechanism in a supported instruction when a machine value must come from instance inputs.

4. Create a local schema set

Save the base dependencies from the validation guide and your custom XSD in a local directory. Add this association to your validator’s schema-set or catalog configuration:

Namespace	Local file
`https://schemas.example.com/neuro/Acknowledgement-v1.xsd`	`Acknowledgement-v1.xsd`

Keep the eight base namespace associations as well. Load the resulting nine schemas and validate the complete custom-acknowledgement.xml file. The custom XSD’s targetNamespace must exactly match the namespace of the embedded Acknowledgement element. Expected result: the complete XML passes. Confirm that your validator also catches these changes, then restore the original document:

Change	Expected result
Set `policyVersion` to `0`	Fail the positive-integer constraint.
Remove `policyVersion`	Fail the required-attribute check.
Use an unknown element namespace	Report a missing schema; do not accept skipped validation.

If your vocabulary imports more namespaces, add each dependency to the same schema set before validating. Retain the exact files and hashes with your contract revision.

5. Prepare provider schema resolution

The selected server implementation checks machine-content namespaces and their imports. It first looks for a stored schema; for an uncached namespace, its normal loader attempts to retrieve the schema using the namespace URI. A namespace that cannot be fetched can produce Schema not downloadable or Unable to get schema file. Before submitting your template:

Replace the example namespace with your controlled, versioned identifier in all three locations described above.
Arrange an XSD location the provider can retrieve. For the normal URI-based loader, serve the XSD at the namespace URI with XML content, without an interactive login page.
Make all imported namespace schemas available through the provider’s supported resolution method.
Give the provider the exact namespace, schema bytes/hash, dependencies, complete contract, and intended data/behavior for review.
Confirm the supported Neuron build resolves and validates the complete contract. Local success alone does not pass this step.

The current Agent API reference does not provide a general schema-registration operation. If you need a non-fetchable identifier or a provider-specific registration process, obtain that supported handoff from the provider. Do not invent a registration request or add an XMPP client connection. The published schema manifest uses SHA-256 to identify files. The selected server records schema references using its own hash metadata; these are distinct records. Do not copy a local checksum into a signed contract field.

6. Submit and verify the template

After the provider confirms schema access and intended support, use the HTTP authoring workflow with your final custom contract file. Observe proposal validation, approval, instance creation, and signatures separately. Keep the exact XSD, namespace, dependency versions, approved template ID, and resulting contract IDs together. A changed schema can change which documents validate. Use a new versioned namespace for breaking changes and obtain a new template review when required. Provider resolution and the custom contract’s live lifecycle have not yet been verified for this example. The supplied tests prove local XML structure and rejection of invalid values only.

Original references

Neuro Foundation documentation: specifications and technical reference material.
Script syntax and function reference: the full language reference.

Authoring resources

Neuron Script

Tools and documentation

1. Choose a namespace and version

2. Define the allowed XML

3. Embed the element in a complete contract

4. Create a local schema set

5. Prepare provider schema resolution

6. Submit and verify the template

Original references

​1. Choose a namespace and version

​2. Define the allowed XML

​3. Embed the element in a complete contract

​4. Create a local schema set

​5. Prepare provider schema resolution

​6. Submit and verify the template

​Original references

1. Choose a namespace and version

2. Define the allowed XML

3. Embed the element in a complete contract

4. Create a local schema set

5. Prepare provider schema resolution

6. Submit and verify the template

Original references