[pournasserian]

Closes #2470

What

The fourth slice of F-SCH (#2415): the schema in a form an agent can write entries from without seeing a screen (SCH-06).

• Descriptions: a definition takes an optional description for the type and for each field, versioned with the rest of the definition. A blank one, or one over 1000 characters, is rejected; leave it out instead.
• Value descriptions: IFieldType.DescribeValue returns a FieldValueDescription: the JSON Schema of one value, an example that satisfies it, and a sentence for agents. Every built-in implements it. reference says that a field reference stores the entity, not a copy of its value. list wraps its item type's description. A field type that is no longer installed is described as any value, so a stored definition that uses one still has a document.
• SchemaDocument: the JSON Schema (draft 2020-12) for one content type, with title, description, properties, required, additionalProperties: false, per-field examples and one example entry. ForSite puts every type under $defs by slug. x-fluentcms carries the slug, version and entity flag.
• Facts: on an entity type every field is an object with value plus source, owner, validFrom, validUntil and lastVerified. All must be present; all but the value may be null, so an agent states that a fact has no source yet rather than leaving it out (ENT-02). A source is {"kind": "url", "reference": "..."}.
• ISchemaDocuments: the document for one type or for the whole site, read through IContentTypeDirectory.

Why

SCH-06 and the epic's goal: an agent can write a valid entry without ever seeing a screen. The document is JSON Schema because that is what agent tooling already validates against, and it fixes the value shapes that F-CNT and F-ENT will check entries against, including the fact envelope.

Choices worth a look:

• Examples come from the field types, never from the author. They are therefore always valid, which the conformance base asserts. Author-supplied examples need value validation, which arrives with entries.
• Descriptions are two sentences joined: the author's description, then the field type's. The field type's sentence is always there, so a document is useful even for a type nobody described.
• A field reference's value is the entity id, not the field value. The description says so, so an agent does not try to write the price into the page.
• Only keywords that mean the same in draft 7 and 2020-12 are used, so the documents validate identically under either dialect. That matters for the test validator below.

New dependency

NJsonSchema 11.6.1 (MIT), test projects only. The tests validate the documents with an independent validator, so they do not grade a schema with the logic that wrote it. No runtime project references it and nothing ships with it.

JsonSchema.Net, the usual choice and the only one with full 2020-12 support, was rejected: from 9.x it is published under a commercial EULA with requireLicenseAcceptance, which does not belong in an open-source repository's build. NJsonSchema is MIT and validates draft 7, which is why the documents stay inside the keyword set both dialects share. The alternatives were LateApexEarlySpeed.Json.Schema (BSD-3-Clause) and Corvus.Json.Validator (Apache-2.0, but a code generator and a much larger dependency tree).

No migration, no pending model change and no new runtime package.

Tests

Conformance: every field type describes its values with a schema its own example satisfies, for every settings sample the base accepts, and has a non-blank description. All ten built-ins and both sample plugin types pass.

Unit: descriptions round-trip through the stored document, a non-string description is reported with its path, and a blank or too long one fails validation. A content type document describes every field, names its required fields and refuses unknown ones, and its example entry validates. An entity type document wraps each field in the fact envelope. A fact may state that it has no source. Eight broken entries each fail: a missing required field, an unknown field, a date that is not a date, an id that is not a uuid, a value outside an enum, a fact without its source, a fact with a bare value, and a source of an unknown kind. The site document holds every type under its slug, and every type's example entry satisfies its own schema. An uninstalled field type is described as any value.

Integration on SQLite and PostgreSQL: every type of the reference scenario model has a document its example entry satisfies, with the entity flag where expected and the author's description in front of the field type's sentence. The site document lists every stored type. A revision shows in the document's $id and descriptions, and an unknown slug fails with content_type_not_found.

The reference scenario model moved into SchemaScenario so the directory tests and the document tests define it once.

Checklist

• Linked to an issue a maintainer has confirmed
• Targets v2
• Tests or docs updated where behaviour changed
• No tool-generated co-author trailers or footers