emsenn

Semiotic Specification

5 min read

This specification is a tooling-contract for specifications: it defines what it means for a document to be a specification in this repository. A document that declares type: specification in its frontmatter commits to following the conventions defined here.

This is not a generic style guide. It exists to make specifications usable as contracts: readable by humans, actionable by agents, and checkable by tools. Each normative statement (MUST, SHOULD, MAY) is a commitment that can, in principle, be validated.

0. Scope

This specification applies to all files under content/technology/specifications/ and to any file elsewhere in the vault that declares type: specification.

Specifications in this repository fall into two categories:

  • Format specifications define serializable artifacts (file formats, wire protocols, data schemas). Sections on canonicalization, error semantics, and determinism apply fully.
  • Convention specifications define organizational practices, governance conventions, or interpretive models. Sections on canonicalization and wire-format determinism are not applicable; sections on versioning, normative language, conformance, and document hygiene apply fully.

Each specification MUST declare which category it belongs to. If unclear, it is a convention specification.

1. Versioning (MUST)

Version identifiers MUST follow MAJOR.MINOR.PATCH where:

  • MAJOR: backward-incompatible changes.
  • MINOR: backward-compatible feature additions.
  • PATCH: backward-compatible fixes and clarifications.

Each specification MUST declare in its frontmatter:

spec-id: "identifier"
version: "MAJOR.MINOR.PATCH"
stability: draft | candidate | stable | deprecated

Wire formats and behavior linked to a MAJOR version MUST remain stable within that MAJOR series.

Stability values:

  • draft: under active development, may change without notice
  • candidate: feature-complete, soliciting review
  • stable: committed, changes require versioning
  • deprecated: superseded, retained for reference

2. Normative language (MUST)

Normative statements use “MUST”, “SHOULD”, and “MAY” in the conventional requirements-language sense (RFC 2119). Every use of these terms in a specification is normative and carries a testable commitment.

  • MUST: absolute requirement. Violation is an error.
  • SHOULD: recommended. Violation is a warning with documented justification.
  • MAY: optional. No violation if absent.

Non-normative text (rationale, examples, history) SHOULD be marked as such, either by section heading (“Rationale”, “Example (informative)”) or by inline annotation.

3. Canonicalization (format specifications only)

Format specifications MUST define a single canonical byte sequence for all serializable artifacts. Rules MUST specify:

  • Field ordering and omission rules.
  • String normalization (Unicode NFC), whitespace policy, and number formatting.
  • Deterministic map/dict ordering.
  • Binary encoding and endianness.

A reference function CANON(x) -> bytes MUST be specified and testable (golden vectors).

Convention specifications MAY skip this section entirely.

4. Error semantics (MUST for format, SHOULD for convention)

Format specifications MUST define error classes with a stable schema. Convention specifications SHOULD define what constitutes a violation and at what severity (error vs. warning).

Ambiguities MUST be treated as errors, not as “unspecified behavior.”

5. Conformance (SHOULD)

Each specification SHOULD provide a conformance matrix listing each normative MUST/SHOULD/MAY statement and the actor(s) it binds (producer, consumer, validator, agent).

For format specifications, an executable conformance suite with golden inputs/outputs, negative cases, and determinism checks is SHOULD-level.

For convention specifications, conformance checking may be performed by the predicate graph satisfaction relation or by dedicated validation skills.

6. Upgrade path (SHOULD)

Specifications SHOULD define:

  • Deprecation process: announcement, dual-stack period, removal.
  • Migration guidance: what changes, what actions implementers take.

7. Security and privacy (MUST for format, MAY for convention)

Format specifications MUST enumerate trust boundaries and required mitigations.

Convention specifications MAY note security considerations where relevant.

8. Determinism (MUST for format)

Format specifications: all observable outputs for the same canonical inputs MUST be bit-for-bit identical across conforming implementations.

Convention specifications: this section is not applicable.

9. Registries (MAY)

If a specification defines extension points (type vocabularies, predicate registries, tag namespaces), it SHOULD define:

  • Registration policy and review process.
  • Collision handling.
  • Each registry entry MUST include: identifier, status, spec reference.

10. Document structure (MUST)

Every specification MUST include:

  • Frontmatter with spec-id, version, stability, and all fields required by semiotic-markdown.
  • Scope section declaring what the spec applies to and whether it is a format or convention specification.
  • Glossary defining terms used normatively.
  • Rationale annex (non-normative) explaining design decisions.

Every specification SHOULD include:

  • Examples marked as normative (golden) or informative (illustrative).
  • Conformance matrix (per section 5).
  • Relationship to other specs listing what this spec requires and extends.

11. Directory structure (SHOULD)

A specification directory SHOULD follow the standard directory organization:

  • index.md — the specification itself
  • concepts/ — concepts introduced by the spec (one per file)
  • terms/ — terms defined by the spec (one per file)
  • methods/ — methods the spec describes for practitioners
  • skills/ — SKILL.md files that implement the spec’s operations
  • scripts/ — executable tooling for validation or generation

Not every subdirectory will exist for every spec. Create only those that have content.

Glossary

  • Specification: a document that makes normative commitments (MUST/SHOULD/MAY) about how something works or is organized.
  • Format specification: a spec that defines serializable artifacts.
  • Convention specification: a spec that defines organizational practices or interpretive models.
  • Normative: binding. A normative statement creates a testable commitment.
  • Informative: explanatory. An informative statement provides context but creates no commitment.
  • Tooling-contract: a spec whose purpose is to constrain how tools (including agents) interact with a domain.

Rationale (non-normative)

This specification exists because specifications without structure are just documents. A document that says “MUST” without defining what violation means, without versioning, without conformance criteria, is making promises it cannot keep.

The distinction between format and convention specifications prevents organizational specs from being burdened with canonicalization and wire-format concerns that do not apply to them, while ensuring they still carry versioning, normative language, and document hygiene commitments.

The requirement for spec-id and version in frontmatter enables the predicate graph to track specification dependencies and detect when a spec’s dependents need updating after a version change.

Relationship to other specs

  • Specializes: specification-specification (the general normative scaffold for any specification).
  • Requires: semiotic-markdown (all specifications are markdown files and follow semiotic-markdown conventions).
  • Conformance layer: semiotic-specification-specification (additional conformance requirements for semiotic specifications).
  • Applied by: all documents with type: specification in this repository.

0 items under this folder.