Use deterministic id attributes for headers in the html spec.

[valerii15298]

Context

I am building a tool similar to swagger editor. And I wanna implement hover tooltips for fields in the spec.
So far I have been using $comment field from https://spec.openapis.org/oas/3.2/schema/2025-09-17.html
Like in this instace to display hover tooltip for parameter

"parameter": {
      "$comment": "https://spec.openapis.org/oas/v3.2#parameter-object",
}

Since most tools(Monaco-editor for example) expect markdown for tooltip hovers I use original markdown spec file from this repo, parse it and extract needed markdown based on $comment field from the schema. (parsing html is not an option because html => markdown is not reliable result)

JS sample code

import { marked } from "marked";

export async function getHeadersMap(markdownURL: string) {
  const spec = await fetch(markdownURL).then((res) => res.text());

  const tokens = marked.lexer(spec);

  const headersMap: Record<string, string> = {};

  tokens.forEach((t, idx) => {
    if (t.type === "heading") {
      const content = [t.raw];
      const name = (t.text as string).replaceAll(" ", "-").toLowerCase();
      for (let i = idx + 1; i < tokens.length; i++) {
        const nextToken = tokens[i]!;
        if (nextToken.type === "heading" && nextToken.depth <= t.depth) {
          break;
        }
        content.push(nextToken.raw);
      }
      headersMap[name] = content.join("");
    }
  });
  return headersMap;
}
const url = "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/versions/3.1.2.md";
const docsMap = await getHeadersMap(url)

---> The above will produce a map id=>content where id is id html attribute from the html spec and content is original markdown content for that id.

The problem arises with fixed-fields id:

 "$comment": "https://spec.openapis.org/oas/v3.2#fixed-fields-10",

Because ids for Fixed Fields headings are incremented globally with a number, for my case I just cannot extract tooltip information for specific field.

Proposal

Can we use deterministic id attributes across the html spec?
So that it would be possible for people to parse original markdown and construct the same id attributes.

Instead of this: https://spec.openapis.org/oas/v3.2#fixed-fields-10

Use id something like this `https://spec.openapis.org/oas/v3.2#request-body-object--fixed-fields

Question

Is there a better way to extract markdown content for specific OpenAPI document field programmatically?

[lornajane]

The HTML output is generated from a tool called respec, so we're not in control of some of those implementation details. While the spec.openapis.org site is the canonical resource, I wonder if your use case might be better served by taking the content from the markdown source. You can find the releases in the versions/ folder of the repository.

[valerii15298]

Yep

I use original markdown spec file from this repo

The thing is that $comment field on the JSON schema for OpenAPI uses url with undeterministic id hash - so that is the problem. I can't map id attribute from html spec to original markdown source when it contains numbers.

I can of course manually insert content for every field but I hoped to avoid doing that.

[valerii15298]

@lornajane and actually I think there is option to use custom id:

https://respec.org/docs/#custom-heading-ids

But maybe there is even better solution, I'm not sure yet.

I general ability to get markdown docs source for particular nested field in openapi document programmatically I think would be useful.

[ralfhandl]

Hi @valerii15298,

The Fixed Fields are typically the first subsection of an Xxx Object, for example the Request Body Object.

The Xxx Object sections have stable and deterministic ids, for example request-body-object.

Why not link to the Xxx Object sections?

[valerii15298]

To display tooltips I use https://spec.openapis.org/oas/3.2/schema/2025-09-17.html schema which has $comment fields which map specific field from the spec to its docs url often. Then I extract those docs from markdown.
And the $comment field in the schema uses fixed-fields, for example this instance:

But because I parse original markdown directly, only for Xxx Object sections it works fine because they have predictable ids. But for fixed-fields-{number} I do not now which section from markdown to get.

I can count myself probably those ids to came up with the same numbers when parsing markdown spec content but I will it will not be reliable and would more seem like reverse egineering respec.

Currently the only solution I found is to first scrape the html to get element by id(fixed-fields-10) then in the DOM get its parent which will have predictable id, then I can find parent by id in the original markdown and then get its fixed-fields...

[handrews]

The JSON Schema specification notes that the contents of $comment MUST NOT be presented to end-users. The appropriate fields for use in a tooltip are title and/or description, not $comment.

[handrews]

@valerii15298 that is, if anything, even farther from the intent of $comment.

[handrews]

@valerii15298 we intentionally decided not to put that sort of information in the schemas because ths schemas are not the specification, and duplicating the information means that it will get out-of-sync with the actual specification.

[valerii15298]

Thank you, that is understandable.

So as I understand tools should on their own parse the document and maintain the descriptions for the fields in sync?

For my case the provided json-schemas are almost ideal and I can just instead of using '$comment` field manually put title/description everywhere and try to keep it in sync. I just thought there would be a better or more automated way of doing that and hoped to avoid syncing it myself 😅

[handrews]

@valerii15298 what's going on here is that you're trying to do a thing that is not inherently unreasonable but is not something that we have ever intended to support.

There are other folks who want the schemas to do various things (it's kind of an endless debate), I'm just describing the current situation.

My main concern is that people understand what they can depend on (because we, the OpenAPI Initiative as a whole, have agreed that they are part of our published interface) vs what they cannot.

For example, we had confusion over people using the wrong schemas from the repository (wrong branches, incomplete schemas with placeholders, etc.), and had to make them harder to find there so that people would use the published ones on the spec.openapis.org site.

So if the project decides to support publishing information in a way that would support the kind of tooltips you want, whether that's through the schema or some other mechanism, that would make tools such as yours viable. Otherwise, I'm afraid we're likely to change whatever you depend on without notice and break your tool. There are too many things we need to do and too few people and hours to treat everything as an interface contract that we commit to maintaining.

[handrews]

@valerii15298 here's the issue where we decided to not have descriptions in the schemas:

• Add field descriptions to JSON schema #1948

Again, this doesn't mean there can't be some solution to your use case, I'm just not quite sure what it is or how we can feasibly commit to maintaining something. But there are other stakeholders here, my view on this is just my view. Informed by reading pretty much every issue ever filed here, but still just my view :-)