OpenGDD

The validator, and what a pass means

Conformance means meeting the OpenGDD specification's requirements. OpenGDD's validator checks the requirements a program can decide from the design files. A person reviews the written design.

Run the checks

The validator runs inside OpenGDD's authoring tool as you write. Nothing to install.

Run the validator from the command line

With Node.js installed, replace <package-dir> with the path to the folder containing the game's design:

npx opengdd validate <package-dir>

To check a build record, name the record and, if you have it, the package it was built from. --render-contract-tests prints the tests that the package's checked contract adoptions imply, as Markdown, without changing any file.

npx opengdd validate --build <opengdd-build.json> [<package-dir>]
npx opengdd validate --render-contract-tests <package-dir>

Exit codes

  • 0: the report has no errors. Warnings never fail a run.
  • 1: the report has one or more conformance errors.
  • 2: the command has a usage error, such as an unknown option or a missing argument.

JSON report

validate --json writes one JSON object to standard output for both passing and failing validation runs. It has these fields:

  • validator names the validation kind; format is the OpenGDD version checked, currently "0.8"; and validator_version is the npm package version that produced the report.
  • package, or build in build-record mode, contains id and path. A package id is null when the package directory could not be read.
  • valid is a Boolean, or null when a build record was checked without its package. verdict is PASS, PASS WITH WARNINGS, FAIL, or NOT CHECKED.
  • summary contains the numeric counts errors, dependent, warnings, and findings.
  • findings is an array. Every finding has code, severity, spec_section, file, and message. line and check-specific data appear when known. dependent: true appears on an error that is waiting for required designer input.

The same checks live in the specification repository. They run on plain Node with no dependencies. Every finding has a stable code, such as PROSE_CITATION_DANGLING. It names the rule and the specification section behind it.

What the validator checks

A package is one folder containing a game's design. The validator checks its files and the connections between them:

  • Required files and fields are present.
  • References in the writing point to defined names.
  • Numbers fall within their declared limits and satisfy the written calculation rules.
  • Data files follow their required structure.
  • Acceptance tests, the checks a finished game must pass, contain the required information.
More detail by part of the package
  • the package: required files present, every declared path inside the package, the manifest valid against its schema;
  • the fantasy block: at least one fantasy line, sentence-ending punctuation, no more than 280 characters across the lines, three to five feel adjectives, and a non-empty NOT: line;
  • values: finite shared numbers under declared keys;
  • ranges: inclusive limits that contain their current values;
  • rules: one comparison between two calculations, with resolvable keys and finite results;
  • personalization: question and answer shapes, with every sets entry aimed at a ranged number and kept inside that range;
  • collections: well-formed collection and record ids, every record held to its schema where one is declared, and no dangling collection or record citation;
  • links: linked records exist, forbidden loops are absent, and declared back-pointers agree in both directions;
  • runtime values: every use has a declaration in a chapter or a clock;
  • clocks: every clock covers every time mode with one of the four behaviour words, and supports any test claim that named runtime values stay unchanged;
  • acceptance tests: ordered headings, one structured test block per heading, and the fields that block requires;
  • art direction: palette and direction shape, dotted references, coverage of every measured promise, and declared WCAG 2.1 contrast floors;
  • contracts: each adoption's answers, numbers, rows and rules against its contract, and that the acceptance tests beside it match the contract they belong to.

Zero errors means the package passed the validator's checks. Warnings ask for another look, but do not fail validation. A person still reviews the written design. Passing validation does not prove that the design is good, or that a finished game follows it.

Build records

The builder is the person, team or AI that turns the package into a game. A build record is the builder's report of that game, stored in opengdd-build.json. It identifies the package, the choices made for that build, the final numbers and the test results.

If you also have the package, the validator checks that the record agrees with it. For example, the final numbers must follow from the recorded answers, and the test totals must add up. These checks read the report. They do not run the game or prove that the report is true.

Auditing a build

An audit examines a finished game and its evidence to check whether it follows the package. OpenGDD's experimental audit protocol describes the process:

  1. Check the package. Run the validator and have a person review the applicable requirements in the writing.
  2. Build and test the game. The builder follows the design, runs every required acceptance test and records the results.
  3. Review the game and evidence. A separate auditor checks whether the tests measure the intended behavior. They also check that the game uses the declared numbers and follows the design.
  4. Verify the report. The auditor checks identities, choices, test results and file hashes. A hash identifies the exact evidence file. The audit records its findings and the limits of the checks made.

The protocol defines experimental verdicts: certify, certify with notes, or do not certify. These are research outcomes. There is no official OpenGDD certification program. These verdicts grant no certification mark.

Limits of the checks

  • Taste. An audit asks whether a build is faithful to its package. It does not decide whether the game is enjoyable. Builds may differ where the designer leaves choices open.
  • Audio. A package may describe audio in prose, but the current standard has no portable checking rules for audio direction.
  • What a player feels or knows. The format can test what is on screen and in the game's state. Those observations do not prove a player's feelings or understanding. The known limitations page draws that line.