Specification-Specification

A specification of specifications. This document defines the normative scaffold — the structural, versioning, error-handling, canonicalization, and document-hygiene requirements — that every specification MUST satisfy to be enforceable as a contract.

This is a format specification: it defines the structure that specification artifacts must conform to.

0. Scope

This specification applies to every document whose purpose is to specify conformance requirements for an artifact, practice, or convention. It provides the drop-in checklist that specification authors MUST work through.

The scaffold has two modes:

• Format specifications: all sections apply (A.1–A.10).
• Convention specifications: sections A.2 (canonicalization), A.7 (determinism), and A.9 (formal artifacts) MAY be omitted with justification. All other sections apply.

1. Transformer surface

A specification is a transformer: it takes inputs, applies constraints, and produces outputs.

• Inputs: a spec artifact and its declared versioning/stability metadata.
• Constraints: normative language and hygiene rules; canonicalization; determinism; conformance mapping.
• Outputs: a conformance matrix; executable tests/fixtures; machine-readable diagnostics for violations.

Current enforcement surface: the normative scaffold checklist (§2).

2. Normative scaffold

The normative scaffold is a drop-in checklist. Each section (A.1–A.10) defines requirements that a specification MUST satisfy. Sections marked “format only” do not apply to convention specifications.

A.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 spec artifact MUST declare spec-id, version, release-date (UTC, YYYY-MM-DD), and stability in {draft, candidate, stable, deprecated}.
• Wire formats and behavior linked to a MAJOR version MUST remain stable within that MAJOR series.

A.2 Canonicalization (MUST — format only)

• 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 omit this section.

A.3 Error semantics (MUST)

• Errors MUST use a stable schema with fields:
  • code (stable, machine-readable), name, severity in {info, warn, error, fatal},
  • where (component/module), when (UTC timestamp), correlation-id,
  • fault (producer/consumer), retryable (bool), data (opaque).
• Define error classes:
  • Input/validation, Canonicalization, Version/feature, State/consistency, I/O/transport, Security/authz.
• Each algorithm step MUST specify which errors it can emit and under what preconditions.
• Ambiguities MUST be errors (not “unspecified behavior”).

A.4 Conformance (MUST/SHOULD)

• Provide a conformance matrix listing each normative MUST/SHOULD/MAY and the actor(s) it binds (producer, consumer, intermediary, validator).
• Publish an executable conformance suite with:
  • Golden inputs/outputs, negative cases, fuzz corpus seeds, and determinism checks.
• Implementations MUST declare a conformance-profile referencing matrix rows and test IDs.

A.5 Upgrade path (SHOULD)

• Specify negotiated capabilities:
  • Feature flags, version ranges, and fallback behavior.
• Define deprecation windows:
  • Announcement → availability of dual-stack behavior → removal.
• Specify migration tools/artifacts:
  • Translators, shims, and data backfills with idempotency guarantees.

A.6 Security and privacy (MUST)

• Enumerate attacker models and trust boundaries.
• State confidentiality/integrity expectations for canonical bytes on the wire and at rest.
• Specify required mitigations (authn/authz, replay protection, input limits, timing channels).
• Define data retention and minimization requirements.

A.7 Interop and determinism (MUST — format only)

• All observable outputs for the same canonical inputs MUST be bit-for-bit identical across conforming implementations.
• Randomness MUST be explicitly parameterized and seeded via inputs; otherwise it is forbidden in normative algorithms.

Convention specifications MAY omit this section.

A.8 Registries (MAY/SHOULD)

• If extension points exist, define:
  • Registration policy, review process, collision handling, and permanence.
• Each registry entry MUST include: identifier, status, spec reference, and security notes.

A.9 Formal artifacts (SHOULD — format only)

• Provide machine-readable schemas (e.g., JSON Schema/ASN.1/IDL) and reference TCK hooks.
• Include pseudo-code that is executable or trivially transpilable.

Convention specifications MAY omit this section.

A.10 Document hygiene (MUST)

• Each MUST/SHOULD/MAY statement is normative and test-mapped (link to conformance ID).
• All examples MUST indicate whether they are normative (golden) or informative (illustrative).
• The spec MUST include a glossary and an explicit non-normative “Rationale” annex.

Glossary

• Normative scaffold: the checklist of structural requirements (A.1–A.10) that every specification must satisfy.
• Transformer surface: the input/constraint/output framing of a specification as a function.
• Conformance matrix: a table mapping each normative statement to the actor it binds and the test that verifies it.
• Golden vector: a normative example input/output pair that conforming implementations must reproduce exactly.
• Conformance profile: an implementation’s declaration of which conformance matrix rows and test IDs it satisfies.

Rationale (non-normative)

This document was promoted from triage/engine/contracts/spec-spec/. The normative scaffold (A.1-A.10) applies to any specification, not only to semiotic specifications. The semiotic-specific conformance layer is in semiotic-specification-specification.

The “specification as transformer” framing makes specifications amenable to tooling: they have typed inputs, constraints, and testable outputs.