concepts

Conformance Scoring

How domain quality scores work — criteria, formula, badge levels, and what drives your score.

What Is the Score?

Every domain in the registry carries a conformance score between 0.0 and 1.0. This score measures how well a schema adheres to quality standards — it's a machine-readable confidence signal for consumers and AI agents.

ℹ️Note

The score is earned, not assigned. It's computed automatically by the registry's conformance engine every time a schema is published or updated.

What Drives the Score

The scoring engine evaluates two dimensions, weighted differently:

Record Coverage
40% of total score
Field Coverage
60% of total score

Within each dimension, points are awarded for:

Completeness

  • Every field has a type declared
  • Every tag has at least one field
  • No orphaned references or broken links between tags

Naming Quality

  • Short, clear field names (avoid customerFirstNameValue → prefer first_name)
  • Consistent kebab-case or snake_case throughout
  • Naming convention compliance with the YON specification

Documentation

  • Descriptions on every tag and every field
  • Context added to metadata (tag_context entries)
  • At least 1 use-case documented per domain
  • Relevant related domains linked (e.g., yon.health links to yon.insurance)
  • External standard links where applicable (ISO, FHIR, etc.)

Technical Validity

  • Parser roundtrip — the schema is parsed by @younndai/yon-parser and the output matches the input. If parsing fails, the schema gets a significant score penalty.
  • Field constraints are valid and non-contradictory (e.g., min ≤ max)
  • Enum values are properly formatted and non-empty

Badge Levels

Scores map to five badge levels:

Improving Your Score

Scores are recalculated on every publish. To improve:

  1. Add descriptions to all fields and tags
  2. Add tag_context entries to metadata
  3. Document at least one use-case
  4. Link to related domains
  5. Fix any parser roundtrip failures
  6. Ensure naming conventions are consistent

💡Tip

The fastest way to improve your score is to add descriptions and context. These two factors account for the majority of the field coverage dimension (60% of total).

Next Steps

Verified Badge
How the Verified badge works — identity + score attestation.
Trust Model
The three trust fields: tier, verified, and score.