OAI / OAI/spec.openapis.org

v3.2: Formats Registry: Inconsistent with the formats in the spec

Open
#39 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

format-registry registries
Dominant language
HTML
Stars
12
Forks
18
Avg merge
7h 31m
Merged PRs (30d)
4

Description

Formats in the spec: https://spec.openapis.org/oas/latest.html#data-type-format
Formats registry: https://spec.openapis.org/registry/format/index.html

In the spec there are 5 defined formats in the table: int32, int64, float, double, password
But in the registry there are 10+ formats for which the source is the OAS

Also for the int64 format there is inconsistency between spec and the registry.
In the spec JSON Data Type for int64 is specified as number but in the registry it is specified as number, string. So it is not clear which type is the accurate one.

Presence of both - the Format registry and the formats table in the spec itself also leads to confusion which one is the source of truth. I would suggest 2 options which would lead to clearer understanding:

  1. Delete formats table from the spec itself and reference the Formats registry as the only source of truth for the formats defined by OAS.

  2. Clarify in the spec that the formats table is only a part of all formats defined by OAS and is only the example.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read the OpenAPI data type format section and the linked Formats Registry index, then compare the listed OAS formats and the int64 JSON Data Type entry. Review the issue's two proposed directions and document a consistent relationship between the specification table and registry, including the int64 definition.

Written by the indexing model from the issue text.

Assessment

Tech stack
html
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.