Contributing

datamodels.jp publishes data models that work in Japan as a shared, product-neutral resource. Anyone can propose and change models, whether a company, a municipality or an individual, and the same rules apply to everyone. Japanese and English are both welcome.

Ways to take part

• Questions, bugs, ideas: open an issue. "I do not understand this attribute" is welcome too.
• Proposing a new model or new attributes: use the model proposal form. No schema is needed yet.
• Adding or changing a model: open a pull request (steps below).
• Proposing upstream: a model that turns out to be useful beyond Japan is proposed to Smart Data Models via incubated. The folder layout matches Smart Data Models for exactly this.

Rules for models

• Built on an existing standard: the catalog publishes models that rest on government or municipal guidelines, Smart Data Models, GIF, an RFC or similar. Record the upstream types you considered, and why they did not fit, in notes.yaml.
• Real data: a model describes data that exists today, not a hypothetical use case.
• Product-neutral: no product-specific annotations or type names (files for particular products come from adapters/).
• The details are in Extending models: namespaces, protected terms, aliases and subclasses, status attributes, writing examples.

Stages and who decides

• Proposal (an issue) → draft (a merged model) → stable → deprecated. A deprecated model stays published; its URLs never change.
• Stable needs two implementations from different organisations in ADOPTERS.yaml. Each entry gives name, organization and a url (public repository, documentation or a contact). CI checks that two organisations are listed; the reviewer of the pull request that sets stable checks that they are real and independent.
• Maintainers review and merge ordinary pull requests. New subjects, major versions and promotions to stable are decided by a small group (Hal, 宮内さん, 大橋さん, Daniel), in the pull request or issue concerned.

Pull request steps

1. Fork the repository and create a branch.
2. Run npm ci. For a new model, npm run new-model -- <subject> <Type> creates the files in the Smart Data Models layout (schema.json, catalog.yaml, examples/, notes.yaml); fill in the TODO markers.
3. npm run validate:models lists what is still missing. Before you push, npm run check and npm test must pass.
4. Sign off every commit with git commit -s and open the pull request.
5. Check the CI results (validation of schemas, examples, @context expansion, protected terms and versions, and an automated review; for branches in this repository also a preview URL) and answer the review.

Recording published versions (snapshots and the manifest) is a maintainer step. Until the official launch (pre-release), the current version may still be corrected in place.

Sign-off (DCO)

Signed-off-by: Name <email> in a commit states that you agree to the Developer Certificate of Origin: you wrote the change or have the right to submit it, and it may be published under this repository's licences. There is no separate contributor agreement.

• How: git commit -s (the name and email must match the commit's author).
• Forgot it: git rebase --signoff origin/main, then git push --force-with-lease. If you would rather not rewrite history, add one follow-up commit that signs off the earlier ones, with the text shown in the DCO check's details.

The DCO app checks that every commit of a pull request (except bots and merge commits) is signed off by its author.

Licences

Machine-readable files (schemas, @context files, vocabularies, examples, catalog.yaml, mapping files, and the published catalog.json and adapter files) are CC0 1.0; prose (notes, the models' READMEs, the site's pages) is CC BY 4.0; the tooling is Apache-2.0. A file that copies content from a CC BY source (Smart Data Models, the GIF core schema) stays CC BY 4.0: name the file and its source in the model folder's LICENSE.md.