Specifications

Conformance

The specification is normative; implementations conform to it. The official icf-conformance test suite is how a conformance claim is checked — including for the official implementations themselves.

Suite 0.1.0 ICF 1.1 · ICX 1.2 44 checks · 32 fixtures github.com/icformat/icf-conformance

What conformance means

An implementation conforms to ICF 1.1 if it satisfies the mandatory requirements of the ICF 1.1 specification and passes the applicable tests of the official conformance suite, subject to declared implementation resource limits.

The suite pins down three observable surfaces, without prescribing internal design:

  • Diagnostics — for each test document, the exact multiset of SEVERITY:CODE pairs. Message wording and line numbers are implementation-defined; severities and codes are not.
  • Data model — the parsed record data, compared as a compact JSON projection.
  • Round-trips — parse → write → parse must preserve the model and the diagnostics; generated ICX must parse back clean.

Every test has a stable identifier (ICF-1.1-VALID-001, ICF-1.1-DIAG-110, …) and maps to the specification sections it exercises.

Verified results

ImplementationVersionICFICXSuite 0.1.0
icfj (Java)1.2.11.11.244 / 44
icfpy (Python)1.2.11.11.244 / 44
icf.js (JavaScript)1.2.21.11.244 / 44

The suite earns its keep: version 0.1.0 surfaced two cross-implementation divergences (the severity of DUPLICATE_SCHEMA_ID, and undeclared-node handling) which were resolved against the Java reference behavior and fixed in icf.js 1.2.2 — the kind of drift a conformance suite exists to catch.

Running the suite

Clone icf-conformance and use the reference runner for your language — each prints one PASS/FAIL line per check and exits non-zero on failure:

# JavaScript          # Python                    # Java
cd runners/js         pip install icfpy           cd runners/java
npm install           python runners/py/run.py    javac -cp icfj.jar Run.java
node run.mjs                                      java -cp "icfj.jar:." Run

Third-party implementations are welcome to use the same fixtures and manifest — the format is documented in the repository README. To claim conformance, state the suite version and result: “Passes icf-conformance 0.1.0 (ICF 1.1): 44/44.” If you believe a test expectation contradicts the specification, open an issue — the specification wins.

Scope and roadmap

Suite 0.1.0 covers the parser + validator surface and the writer via round-trips and ICX generation. Planned for future versions: canonical serialization checks, resource-limit behavior, Unicode edge cases, full ICX index-content verification, and reconciliation of the remaining known divergence (FIELD_COUNT_MISMATCH severity).