Pre-release. Until the official launch, content may change, including published files.
Skip to content

Source: https://datamodels.jp/en/guide/contribute · Text CC BY 4.0

Contributing ​

Anyone can take part: a company, a municipality or a single person. The same rules apply to everyone. Japanese and English are both fine.

To ask for something, use the issue form that fits. An issue form is a page on GitHub with fields to fill in. You need a free GitHub account (sign up). Each section below says when to use a form, what it asks and what happens next.

Nothing goes from a form straight onto the site. A maintainer checks your request first. Then the change goes into the catalog in a pull request (a proposed change to the catalog's files) that passes the automatic checks and a review.

Issues are public: never write passwords, API keys, tokens or login URLs in them.

For a question, a bug or an idea, open a plain issue. "I do not understand this attribute" is welcome too.

Propose a model or attributes ​

Use the model proposal form for a new model, or for new attributes that most users of a model need. You do not need to write a schema.

What the catalog accepts is in Rules for models: among other things, a model rests on an existing standard and describes real data. A model that only your project needs can go on your own site instead (Your own data models). To add attributes for yourself only, or to change only the names, you need no proposal (Which page do I need?).

The form asks what one record represents, who holds such data today and roughly how much, and the standard the model rests on (if none fits, say why). If you know them, add a second organisation that would use the model, and a sample record. After you open the issue, a comment lists similar models that already exist: check whether one of them can be used or extended.

What happens next: we discuss the proposal in the issue. Then you or a maintainer write the model in a pull request (Changing the files yourself); you do not need to write code yourself. Once it is merged, the model is published as a draft. It becomes stable when two different organisations use it in their own systems (Stages).

Proposalan issueDraftin the catalogStableready to rely onDeprecatedstill publishedreview, merge2 organisationsnot for new work

Open the model proposal form

List your extension ​

Did your organisation add attributes to a catalog model? Then use the extension form to show them on the model's page, under "Built on by others". Others who need an attribute with the same meaning can reuse your name, so your data and theirs fit together. If you publish your models on a site made with the toolkit, you need no form: list your site instead (next section), and the model page shows its models by itself.

The form asks for the model you extended (for example task/Task), your organisation's name in Japanese and English, and each added attribute with its name, IRI and meaning. An IRI is a web address that names an attribute: use one under a domain you control, such as your organisation's website. It also asks for your @context and the version you built on. You confirm that you speak for the organisation, and that anyone may reuse the text (CC0 1.0). When you open the form from the model page (the link "list your extension"), the model is already filled in. New to @context? See Adding attributes. The extension builder makes the @context for you.

What happens next: a maintainer checks that you speak for the organisation. A maintainer (or you, if you like) adds the entry in a pull request, and automatic checks catch mistakes, such as a name that clashes with an attribute of the model. Once it is merged, your organisation shows on the model page and in catalog.json within minutes. The attributes are listed as you report them: datamodels.jp does not review their design. An example of a filled-in form: #189.

Open the extension form

List your data model site ​

Do you publish your own data models on a site made with the toolkit (Starting a site)? Then use the site listing form to put the site on the list of Data model sites. If a model of your site builds on a catalog model, that model's page shows it too, under "Built on by others", with the attributes it adds.

The form asks for the site's URL, the URL of its catalog.json, and its name in Japanese and English: the title in catalog.json, else the publisher name. The list uses it. You confirm that you run the site, or that you ask on behalf of the people who run it. You also agree that datamodels.jp lists the site and its models. When the site moves or closes, tell us in an issue.

What happens next: a maintainer adds the site to the list in a pull request. The pull request also reads the site's catalog.json, and a review checks what was read. datamodels.jp does not review the models themselves: each site decides about its own.

Open the site listing form

Tell us about another catalog ​

Do you know a catalog of data models or vocabularies that is missing on Other data model catalogs? Then tell us with the catalog form. A standard layout for data, such as the municipal standard open datasets, counts too. It can be global, Japanese, or from one organisation. Anyone must be able to read it without a login or a contract.

The form asks for the catalog's name, its page, who publishes it, its scope, what it covers and in which formats, how it relates to datamodels.jp, and its licence. Not sure about a field? Write what you know, or "unknown". The maintainer can ask.

What happens next: a maintainer looks at the catalog and may ask you a question in the issue. If it fits, a pull request adds it to the page.

Open the catalog form

Changing the files yourself ​

To send a request, the forms above are all you need. If you change the catalog's files yourself in a pull request, follow CONTRIBUTING.md on GitHub: the pull request steps, who decides and the sign-off (DCO). What you contribute is published under the catalog's licences.