w3c-technical-reports

W3C technical reports

Turn an approved technical design into a precise specification. Improve expression and structure without creating policy, consensus, conformance criteria, or requirements.

Establish authority and scope

• Identify the source of approved requirements and the decision body that owns them.
• Preserve requirement strength, actors, conditions, exceptions, algorithms, data types, error behavior, and compatibility constraints.
• Do not infer a normative requirement from an example, implementation, issue discussion, preference, or common practice.
• Mark unresolved decisions and contradictions as issues. Do not silently choose a behavior.
• State the document's scope, out-of-scope concerns, maturity, and intended implementations.

Build the conceptual model

1. Identify each conformance class, implementation role, data model, and external dependency.
2. Define a term before using it to carry a requirement. Use one stable term per concept.
3. State how terms relate when they can be confused or overlap.
4. Present the processing model in an order that exposes inputs, state changes, outputs, and errors.
5. Keep implementation-specific behavior out unless the scope intentionally requires it.

Write normative requirements

• Give each requirement an identifiable actor and one testable obligation.
• Put conditions and scope next to the behavior they constrain.
• State exceptions explicitly and identify which rule they override.
• Describe observable outcomes without prescribing an implementation method unless the method is itself required for interoperability or safety.
• Keep conformance requirements in normative prose. Label examples, notes, rationale, and implementation advice as informative.
• Do not place a requirement only in a figure, table, example, or note.

Use RFC 2119 and RFC 8174 key words only when the governing document deliberately adopts their definitions. In that case, only the uppercase forms carry the defined meanings. Do not upgrade ordinary advice to MUST, SHOULD, or MAY; preserve the strength approved by the specification owners. Explain a deviation from a SHOULD requirement when the source calls for it.