MdFlow

Appearance

2. Conformance ​

2.1 RFC 2119 keywords ​

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

Clauses marked normative MUST be implemented by conforming implementations. Clauses marked informative are explanatory and impose no requirements.

2.2 Conformance classes ​

MdFlow defines two conformance classes. An implementation MAY claim conformance to one or both. A conformance claim MUST state which class or classes it satisfies.

2.2.1 Class B — Batch ​

A Class B (Batch) implementation accepts a complete source document and produces the defined output in a single pass. Class B implementations:

2.2.2 Class S — Streaming ​

A Class S (Streaming) implementation accepts source as a sequence of chunks and produces output progressively. Class S implementations:

  • MUST pass every vector in the conformance suite, including vectors tagged class: streaming and class: both.
  • MUST implement all chapters, including §5 Streaming Model.
  • MUST satisfy the incremental idempotency requirement (§5.4).
  • MUST produce output that, at end-of-input (flush() called, then no further input), is identical to the output a Class B implementation would produce for the concatenated source.

A Class S implementation trivially satisfies Class B by concatenating all chunks and calling flush() once. Implementations MAY declare both classes.

2.3 Conformance targets ​

The specification distinguishes four targets that MAY be implemented independently:

  • Parser. Takes source text (or chunk sequence) and produces a document tree (§3). A Parser MUST pass vectors whose expected output is a tree.
  • Renderer. Takes a document tree and produces DOM or serialized markup. A Renderer MUST pass vectors whose expected output is DOM or HTML.
  • Full stack. Takes source (or chunks) and produces DOM or serialized markup. A Full stack MUST pass every vector not restricted to Parser or Renderer.
  • Extension host. Supports the plugin mechanism (§9). An Extension host MUST pass the extension vectors and SHOULD be paired with one of the three targets above.

A conformance claim MUST state the target(s).

2.4 Conformance vectors ​

Normative behavior is defined not only by prose but by the conformance suite (§13). Every normative MUST / MUST NOT clause in this document has at least one vector. Where prose and a vector disagree, the vector takes precedence; such disagreements are errata candidates and MUST be reported via the governance process.

2.5 Extension conformance ​

Conformance to the core specification does not imply conformance to any extension specification (e.g., md-clock, md-plot). An extension conformance claim MUST cite the extension specification by name and version.

2.6 Claiming conformance ​

A conformance claim is a prose statement of the form:

Implementation X version Y claims conformance to MdFlow v1.0, Class {B | S | B+S}, target {Parser | Renderer | Full stack | Extension host}, as verified by the vectors at commit Z.

Implementers SHOULD publish the vector results alongside the claim.

2.7 Non-conformance ​

An implementation that fails any normative MUST clause is non-conforming to the claimed class. Implementations MAY publish partial-conformance reports (vectors passed / failed). Partial-conformance is not a conformance class.

2.8 Interpretation of silence ​

Behavior the specification does not mandate is undefined. Implementations MAY choose any behavior for undefined cases, but SHOULD document their choices. Reliance on undefined behavior in source text is non-portable.