v3.2: Formats Registry: Inconsistent with the formats in the spec
Nobody has claimed this yet.
- 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:
-
Delete formats table from the spec itself and reference the Formats registry as the only source of truth for the formats defined by OAS.
-
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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