OpenAPI format for type IDs

[Le0Developer]

We currently use an OpenAPI schema like this for TypeID:

"schema": {
    "type": "string",
    "pattern": "^user_[0-7][0-9a-hjkmnpq-tv-z]{25}$",
    "example": "user_01jv1sm13xf02v44y3j8b66d7k",
    "format": "typeid"
}

As you can see, there's no field for the prefix ("user") that can be programmatically consumed (without parsing the pattern/example). So I'm wondering, what would the field for that be? x-typeid-prefix?

[klimeryk]

Thanks for opening this issue - and sharing your regexp for validating TypeID! I just wanted to leave a note that the regexp seems to be missing the p character. It is part of the alphabet for the UUID suffix, as per the specification.

The encoding uses the following alphabet 0123456789abcdefghjkmnpqrstvwxyz

So, the regexp should be ^user_[0-7][0-9a-hjkmnpq-tv-z]{25}$. Or ^[a-z]([a-z_]{0,61}[a-z])?_[0-7][0-9a-hjkmnpq-tv-z]{25}$ if someone needs a more generic one 🙌

[Le0Developer]

🤦 I was close! Thanks, I've edited the comment.

[mrlubos]

@Le0Developer how do you end up with format: typeid in your OpenAPI spec? Are you doing this manually?

[Le0Developer]

@Le0Developer how do you end up with format: typeid in your OpenAPI spec? Are you doing this manually?

Yes, we use swaggo for generating documentation from our Go API's source code and then run a python script to fix some issues it has. Among those "fixes" we have a check if the "example" value is a typeid and then add the pattern and type fields accordingly. The result is an field like above.

[mrlubos]

So my main concern is whether we can agree on using format: typeid as a standard way of describing TypeID values in OpenAPI/JSON Schema. What you propose makes sense to me, but would love to hear from @loreto

[loreto]

I support format: typeid. I'm tempted to nest prefix inside x-typeid to allow for additional fields later.

In OpenAPI YAML, that might look like:

    schemas:
      User:
        type: object
        properties:
          id:
            type: string
            format: typeid
            pattern: ...
            x-typeid:
              prefix: user
            example: user_01jv1sm13xf02v44y3j8b66d7k

Thoughts?

[mrlubos]

What other fields might you want to contain in x-typeid later?