Skip to content

Commons guide: lead with the strict-fields rule and the extension paths #420

Open

Description

@cuibonobo

Problem

A Record carrying a content field its Type doesn't declare is refused with 422 at every depth (data-model.md § Undeclared content fields), and commons types must be registered exactly as written. That is the right rule: a typo has to fail loudly, not land in a field no reader looks at. But the commons guide mentions it in passing under "Canonical definitions", and it's easy to come away believing a commons Record can carry extra fields that other apps simply ignore.

The guide also ranks the ways an app can use commons types "in order of preference", which reads as a judgment on apps that define their own types.

Decision

  • Lead with the rule and the sanctioned paths, before the postures:
    • propose the field upstream (additive optional fields land in place);
    • an app's own sidecar type, linked by a relationship association;
    • an app's own type that satisfies isCompatible() with the commons type;
    • an open container, where the type declares one.
  • Describe the postures rather than rank them: what each buys and costs, without "in order of preference".

Actions

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions