# XML schemas

Define form fields and data contracts directly in XML. This standalone dialect describes JSON Schema; it does not change the validation engine. Embed its `schema` root inside an authoring node that accepts schemas: integration `configuration-schema`, Action `input-schema`, `config-schema` and `output-schema`, container `json-schema`, EdgeApp `config-schema`, workflow `input-schema`, workspace handler `input`/`output`, or journey `schema`.

## A configuration form

```xml
<config-schema>
  <schema xmlns="urn:cococo:json-schema:1" type="object" additional-properties="false">
    <property name="endpoint" type="string" format="uri" required="true">
      <description>Service endpoint</description>
    </property>
    <property name="token" type="string" input-type="password" required="true"/>
    <property name="device" type="string" related-resource="device" resource-value-field="id"/>
    <property name="retries" type="integer" minimum="0">
      <default type="integer">3</default>
    </property>
    <property-order><name name="endpoint"/><name name="token"/><name name="device"/><name name="retries"/></property-order>
  </schema>
</config-schema>
```

A prefix such as `s:schema` with `xmlns:s="urn:cococo:json-schema:1"` is equivalent. Namespace declarations may be placed on an ancestor. Schema elements use that namespace; ordinary resource elements keep their own vocabulary.

## Constraints and composition

String constraints are attributes: `anchor`, `comment`, `content-encoding`, `content-media-type`, `description`, `dynamic-anchor`, `dynamic-ref`, `format`, `id`, `meta-schema`, `pattern`, `ref`, `title`. Numeric constraints: `exclusive-maximum`, `exclusive-minimum`, `max-contains`, `max-items`, `max-length`, `max-properties`, `maximum`, `min-contains`, `min-items`, `min-length`, `min-properties`, `minimum`, `multiple-of`. Boolean attributes: `deprecated`, `read-only`, `unique-items`, `write-only`. `type="string null"` declares a union; `boolean="false"` is a schema that accepts nothing.

Use `property name="…"`, `pattern-property name="…"`, `definition name="…"` and `dependent-schema name="…"` for named schemas. Optional `properties`, `pattern-properties`, `definitions` and `dependent-schemas` containers group their corresponding named children and preserve empty maps. `required-properties` contains name children and can represent an empty required list. `required="true"` on a property adds its name to the enclosing required list; `<required name="…"/>` also supports required names without a property declaration.

`additional-properties`, `contains`, `content-schema`, `else`, `if`, `items`, `not`, `property-names`, `then`, `unevaluated-items`, `unevaluated-properties` contain schema constraints directly. They also accept boolean attribute forms, such as `additional-properties="false"`. `all-of`, `any-of`, `one-of`, `prefix-items` contain ordered `<schema>` children. References retain JSON Pointer syntax: `ref="#/$defs/entry"`. The host's reference rules still apply.

`<dependent-required name="field"><name name="other"/></dependent-required>` describes a dependency. `<vocabulary uri="…" required="true"/>` declares a JSON Schema vocabulary.

## Values without type guessing

Defaults, constants, examples and enum choices use explicit types. A string `0012` remains a string; null, false and zero stay distinct.

```xml
<schema xmlns="urn:cococo:json-schema:1" type="string">
  <enum><value type="string">small</value><value type="string">large</value></enum>
  <default type="string">small</default>
  <enum-labels><value name="small" type="string">Small format</value><value name="large" type="string">Large format</value></enum-labels>
</schema>
```

`default`, `const`, and the platform `example` annotation take `type="string|integer|number|boolean|null|object|array"`. Object values contain `<value name="…" type="…">`; arrays contain unnamed `<value>` children. `enum` and `examples` contain typed values. Strings preserve whitespace. Use XML escaping for `<` and `&`; CDATA is also available for literal text inside a typed value.

## Form and platform annotations

These native names compile to the existing annotations, so forms, resource lookups, secret extraction and expression tooling see the same contract.

| XML name | JSON annotation | Value kind | Purpose |
| --- | --- | --- | --- |
| `input-type` | `x-input-type` | string | Form input type; password marks a secret, text requests a text input. |
| `editor` | `x-editor` | string | Form editor, such as code. |
| `editor-language` | `x-editorLanguage` | string | Language for the code editor. |
| `related-resource` | `x-relatedResource` | string | Resource used by a form lookup. |
| `resource-value-field` | `x-resourceValueField` | string | Field returned by the resource lookup. |
| `property-order` | `x-propertyOrder` | strings | Explicit form field order; use one name child per property. |
| `supports-expression` | `x-supportsExpression` | boolean | Whether expressions are permitted. |
| `expression-format` | `x-expressionFormat` | string | Expression syntax: path, template or predicate. |
| `expression-depth` | `x-expressionDepth` | integer | Depth to which expression support is inherited. |
| `expression-container-only` | `x-expressionContainerOnly` | boolean | Expressions belong in descendants, not the container itself. |
| `expression-evaluation` | `x-expressionEvaluation` | string | Expression evaluation mode. |
| `expression-result-schema` | `x-expressionResultSchema` | schema | Expected result schema for an expression. |
| `dynamic-schema` | `x-dynamicSchema` | string | Resource and field providing a dynamic form schema. |
| `query-parameter-bindings` | `x-queryParameterBindings` | string | Query field whose parameters populate bindings. |
| `ai-hint` | `x-aiHint` | string | Author guidance for AI-assisted use. |
| `node-type` | `x-nodeType` | string | Workflow node type identity. |
| `icon` | `x-icon` | string | Presentation icon. |
| `group` | `x-group` | string | Presentation group. |
| `example` | `x-example` | value | An example value. |
| `enum-labels` | `x-enum-labels` | stringMap | Human-readable labels keyed by enum value. |
| `enum-values` | `x-enum-values` | valueMap | Structured values keyed by enum value. |
| `dimension` | `x-dimension` | string | Product-template dimension; subject to host validation. |
| `applies-to` | `x-applies-to` | strings | Product-template components to which this property applies. |
| `visible-when` | `x-visibleWhen` | valueMap | Workflow visibility condition with field and equals entries. |
| `visible-when-values` | `x-visible-when` | valueMap | Product-option visibility conditions keyed by property name. |
| `placeholder` | `x-placeholder` | string | Placeholder shown in the field. |
| `unit` | `x-unit` | string | Unit suffix displayed alongside the value. |
| `secret` | `x-secret` | boolean | Credential hint for consumers supporting workflow secret annotations; integration secrets use input-type=password. |
| `binding` | `x-binding` | boolean | Workspace field accepts a data binding. |
| `items-from` | `x-itemsFrom` | string | Sibling array binding used for item-relative fields. |
| `journey-picker` | `x-journeyPicker` | boolean | Select a published journey. |
| `suggested-enum` | `x-enum` | values | Suggested values used by workflow configuration editors. |
| `category` | `x-category` | string | Workflow palette category identifier. |
| `categories` | `x-categories` | values | Ordered workflow palette category descriptors. |
| `target` | `x-target` | string | Product-option target kind. |
| `target-field` | `x-target-field` | string | Product-option target field. |
| `passthrough` | `x-passthrough` | boolean | Output preserves its input shape. |

Scalar annotations are attributes, or text children when longer prose is easier to read. Name lists accept whitespace-separated attributes such as `property-order="endpoint token device"`; for names containing whitespace, use `<name name="…"/>` children. Maps use typed `<value name="…" type="…">` children. `expression-result-schema` contains schema constraints directly. An annotation only affects the host consumers that implement it; product-template annotations do not become integration behavior merely by being present.

## Compatibility and validation

Existing JSON text and JSON inside CDATA remain accepted in schema-bearing nodes. Use exactly one representation: JSON text/CDATA, or one XML schema root. Mixing them, duplicate keywords and unknown XML names are errors. Authored source is preserved. Generated XML prefers native schemas; a serializer must retain JSON rather than drop a keyword it cannot represent.

Host restrictions remain in force. Workspace handler contracts intentionally accept a narrower schema vocabulary; XML does not enable references, unrestricted alternatives or annotations at that boundary. Integration schemas retain local-reference restrictions. XML parsing prohibits DTDs and external entities, and existing source, nesting and output limits still apply.