Redocly / Redocly/redoc

Link to schema from description etc

Open
#1,268 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

Is it possible to create links and/or embed other schemas in the description of a property?
I saw that in #681, support for <SchemaDefinition> tags was added, but apparently only to tag descriptions?

My use case is this: The API has multiple instances of encrypted data containers. In encrypted form, the data always has the same structure (containing a public key fingerprint, an ephemeral key encrypted with said public key, etc - standard hybrid encryption), so this is defined in a re-used schema obviously. But it's also useful to describe the schema for the raw/source JSON data once the encrypted data container is decrypted, so API consumers know how to parse the decrypted data.

Example:

EncryptedData:
  description: Generic encrypted representation of arbitrary data
  type: object
  properties:
    data:
      type: string
      format: byte
      description: The data encrypted with the ephemeral key
    encryptedKey:
      type: string
      description: The ephemeral AES key, encrypted with the public RSA key
    publicKeyFingerprint:
      type: string
      description: The fingerprint of the public RSA key

Some.SourceData:
  type: object
  description: Some data we want to encrypt
  properties:
    foo: {type: string}
    bar: {type: integer}

Some.Request:
  type: object
  properties:
    encryptedData:
      allOf:
        - description: Encrypted data container containing the encrypted representation of a `Some.SourceData` object
        - $ref: '#/EncryptedData'

In this case, Some.Request contains an encrypted container of a Some.SourceData object (so you'd get the raw object from something like JSON.parse(decrypt(req.body.encryptedData))).

In my spec, I've included the schemas for the decrypted raw representation as well, but it will be an orphaned object without any references to it, since it's not actually part of any other schema or API, it's only there to describe the schema of another object after it's been decrypted (or before it's been encrypted).
To at least include it in my documentation, it would be nice if I could link to it so that when viewing the Some.Request operation, I can expand it and find that encryptedData is of type EncryptedData but in decrypted form it'll be a Some.SourceData.

I think that this would be possible if <SchemaDefinition> were supported on any description element, but maybe that makes the layout too complex? Is there any other way to link one schema description to another, or in any other way achieve what I'm after?

Or should I consider the schema of decoded/decrypted objects separate entities and leave them out of my API altogether? It seems reasonablethat a server implementing this API would get a Some.Request request, validate that the body matches the schema, i.e., that encryptedData is valid, then decrypt encryptedData, parse it into a object, and then validate it using the schema of the raw data.

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

Start by reviewing the existing support referenced in #681 and how property descriptions are rendered. Define whether links or embedded schema references should work in arbitrary descriptions, then verify that the encryptedData example makes Some.SourceData discoverable from the operation documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.