# `fvj1:` conformance fixture

`fvj1-conformance.json` records what this package's JSON codec does with a set
of values and texts, so that an implementation of the `fvj1:` format in another
language, or of another wire format that has to agree with it, can test itself
against the same cases. The format is specified in
[`3-json-encoding.md`](../../../../docs/specs/space-model-formal-spec/3-json-encoding.md)
and
[`1-fabric-values.md`](../../../../docs/specs/space-model-formal-spec/1-fabric-values.md).

The file is generated by `deno task regenerate-fvj1-conformance`, run in
`packages/data-model`, from the cases in `src/fvj1-conformance.ts`, and
`test/fvj1-conformance.test.ts` fails whenever the file and the codec disagree.
Edit the cases, not the file.

## Entries

The file is JSON, holding only ASCII: every other character is escaped. Its
`cases` list holds one object per case:

- `name`: unique among the cases.
- `section`: the part of the spec the case exercises.
- `encode`: a value, under `value`, and either the exact text encoding it
  yields, under `text`, or `refused: "unencodable"`.
- `decode`: a text, under `text`, and either the value decoding it yields, under
  `value`, or the reason it is refused, under `refused`: `not-fvj1` when the
  text lacks the prefix, `not-json` when what follows the prefix is not JSON,
  and `malformed` for any other form the format does not allow. The spec settles
  all three alike, so a decoder need only refuse; the kind says why.
- `divergence`: present where this package falls short of the format, as the
  spec states it. The `encode` and `decode` beside it are then the format's
  outcomes, computed by the generator rather than written by hand, and
  `divergence.encode` and `divergence.decode` are this package's, given only
  where they differ. `divergence.note` says what the format requires.

An entry has `encode`, `decode`, or both. A value whose text decodes back to it
has both, with the same value and text. A text that is not the canonical form of
the value it decodes to has an `encode` giving that canonical form.

A refusal is recorded only where the codec refused; a fault in the codec fails
generation instead. Refusals assume a strict decoder. A lenient one returns a
`Problematic` value in place of raising, at the point of the malformation.

## Exact text

An encoder that is to match `text` byte for byte writes the JSON that
ECMAScript's `JSON.stringify()` writes with no indentation, as ECMA-262 defines
it: a string by the `QuoteJSONString` abstract operation, and a number by
`Number::toString`. The result is JSON as RFC 8259 defines it. Record keys are
in the order section 10 of the spec requires, UTF-8 byte order, a lone surrogate
taking the bytes WTF-8 gives it.

## Descriptors

A `value` is a descriptor, in the notation
[`value-descriptors.md`](value-descriptors.md) defines: JSON that says
everything about a value the format carries, and nothing about how the format
carries it. A `cycle` descriptor appears in none of the cases, this package's
codec refusing to encode a value with a cycle. `Map` and `Set` values are in the
notation but not among the cases, their codecs being stubs pending general
`FabricInstance` support. `name` in an `Error` is the error's name even where
the wire writes `null` for a name equal to the type.