> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Author a custom contract schema

> Define your own machine-readable XML, validate a complete contract locally, and prepare schema resolution for provider review

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](/downloads/examples/Acknowledgement-v1.xsd). The file uses a reserved example address:

```text theme={null}
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 theme={null}
<?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](/downloads/examples/custom-acknowledgement.xml). It extends the [acknowledgement tutorial](/contracts/from-scratch) with custom machine-readable data:

```xml theme={null}
<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.

<Accordion title="Complete custom-schema contract">
  ```xml theme={null}
  <?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>
  ```
</Accordion>

`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](/resources/validate-xml) 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:

1. Replace the example namespace with your controlled, versioned identifier in all three locations described above.
2. 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.
3. Make all imported namespace schemas available through the provider's supported resolution method.
4. Give the provider the exact namespace, schema bytes/hash, dependencies, complete contract, and intended data/behavior for review.
5. 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](/contracts/from-scratch#3-propose-the-template) 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](https://neuro-foundation.io/Index.md): specifications and technical reference material.
* [Script syntax and function reference](https://lab.tagroot.io/Script.md): the full language reference.