liveBook · Manning

Child document

As explained in Automating API Delivery

An external API fragment is a separately stored JSON or YAML document containing part of an API definition that is referenced from a parent document.

A child document is an external JSON or YAML fragment that stores part of an OpenAPI definition. A parent document references it with $ref, combining a file path and a JSON Pointer to the target object. section 8.13

Use a consistent split structure when organizing a multifile API definition:

  • Give each header, success response schema, and error response object its own file; path child documents may contain multiple operations. section 8.13.1
  • Include both the child-document path and JSON Pointer in every external reference, such as paths/v1-catalog-categories.yaml#/paths/~1v1~1catalog~1categories. section 8.13.1
  • Make each fragment a valid OpenAPI document when linting, transformation, editor assistance, or independent fragment versioning matters; the OAS itself does not require this structure. section 8.13.1

Referencing a path child document

A parent definition can map /v1/catalog/categories to $ref: 'paths/v1-catalog-categories.yaml#/paths/~1v1~1catalog~1categories'. The child file can then contain the path object and its operations, while related headers and schemas remain in component files. section 8.13.1

openapi: 3.0.3
info:
  title: Product Catalog API
        version: 0.0.1
…
tags:
  - name: Categories
    description: A category is a class of products 
 with common characteristics
…
paths:
  /v1/catalog/categories:
    $ref: 'paths/v1-catalog-categories.yaml#
 /paths/~1v1~1catalog~1categories’          #1
  /v1/catalog/products:
    $ref: ‘paths/v1-catalog-products.yaml#
 /paths/~1v1~1catalog~1products’           #2
  /v1/catalog/products/{id}:
    $ref: ‘paths/v1-catalog-products-id.yaml#
 /paths/~1v1~1catalog~1products~1{id}'
  /v1/catalog/products/{id}/reviews:
    $ref: 'paths/v1-catalog-products-id-reviews.yaml#
 /paths/~1v1~1catalog~1products~1{id}~1reviews'
components:
  securitySchemes:
    $ref: 'components/securitySchemes/OAuth2.yaml#
 /components/securitySchemes'
security:
  - OAuth2: []

Browse a parent OpenAPI definition showing external references for paths and security schemes. section 8.13.1

For a large monolithic definition, Redocly CLI can create an initial multifile layout with `redocly split product-catalog.oas.yaml --outDir out`. Its generated fragments may contain only reference objects, so teams may convert them into full OpenAPI documents afterward. section 8.13.4

How Automating API Delivery covers it

How deep it goes
Defines external references, file layout, and JSON Pointers, while noting that OAS does not prescribe child-document structure.
Examples
Uses catalog path files, component headers, response schemas, security schemes, and Redocly CLI splitting.
What it assumes
Assumes familiarity with OpenAPI objects, $ref references, URI paths, and JSON Pointer fragments.
What you can do after
Apply it via Redocly CLI and construct parent references that resolve to external OpenAPI fragments.
How it connects
Connects OpenAPI reference objects, JSON Pointer, reusable components, and multifile API definitions.
Cover of Automating API Delivery
liveBookmanning.com
Read Automating API Delivery on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Automating API Delivery. The section links point to the parts of the book it draws on.