OpenAPI Slimmer - Schema Filter Tool

No Clocks
How to Generate JSON Schema Effectively and Efficiently
Creating a JSON schema can be a crucial step in ensuring data consistency and quality, especially when dealing with APIs and data exchange. Below is a detailed guide on how to create a JSON schema:
https://yamlcraft.studio/
API Spec Validator | Appear
Upload your API spec and see validation errors directly mapped to your code.
OpenAPI 3.1 - The Cheat Sheet
Everything you need to keep in mind when writing an OpenAPI contract, on a one-pager.
The Perfect Modern OpenAPI Workflow
Discover how OpenAPI can revolutionize your API development process with a streamlined, Git-centric workflow. Learn about design, governance, and automated deployment of documentation, mocks, and SDKs, all while maintaining a single source of truth.
Hoisting | Speakeasy
Hoisting enables flattening of an API request or API response body to make it more tightly align with the resource semantics.
Josiah Parry - Enums in R: towards type safe R
PROPERTY
LAND
Data Dictionary | RESO - Real Estate Standards Organization
The RESO Data Dictionary is the real estate industry’s universal language for data. It allows a wide range of systems to talk to each other in a seamless manner. The Read More »
I came across this Reddit thread: https://www.reddit.com/r/golang/s/Bv7TPIvVlM...
The discussion around API vs DB vs domain models is particularly relevant to LandRise's architecture, given its integration with the Real Estate API (REAPI)...
Loading large nested JSON files into Azure SQL db using Azure Data Factory - Microsoft Q&A
Hi all,
I am currently working with large nested JSON files stored inside a blob container. Each file has a different structure with varying fields and data types, and nested arrays.
My goal is to load these files into an Azure SQL database in an…
seascapemodels
Marine Science
Extending Object Definitions With OpenAPI's allOf
Did you know you can define object inheritance using OpenAPI?
Getting Creative with OpenAPI - by David Biesack
Defining resource creation and update operations with OpenAPI
unevaluatedProperties: false
This article pulls in lots of aggregated knowledge from earlier articles in the Language of API Design series:
Mapping a domain model to OpenAPI
Patterns for clean URLs and URL structure
Defining the request body for a POST operation
Defining API responses with OpenAPI response objects and response body data format with JSON Schema
Composing JSON Schemas to keep the OpenAPI definition DRY
Understanding the subtleties of JSON schema (notably, unevaluatedProperties)
Defining reusable response objects to keep the OpenAPI definition DRY
Defining how the API handles problems with client requests as well as server errors
Validating API Requests - by David Biesack
Techniques for API Request Validation
A promise of REST APIs is good decoupling of clients and services. This is achieved in part by reducing business logic as much as possible in the client application. For example, a client application may use a form for collecting information used in a POST operation to create an API resource, or to edit an existing resource before updating it with a PUT or PATCH operations. The client then maps the form fields to the properties of the operation’s request body. Clients can use front end frameworks and libraries to perform lots of low-level validation in the front end corresponding to JSON schema constraints.
However, this only covers “syntactic” or static field-level validation. Often, an API will also have business rules that the client must follow. Secure API services will enforce those business rules in the API operations
Parse the options and (JSON) request body and return a 400 Bad Request if any of the request data is malformed (i.e. does not satisfy the constraints of the operation (such as required body or required parameters) or all the JSON Schemas associated with the operation’s parameters or request body)
Verify that the caller passes valid Authorization to the API call, and return 401 Unauthorized if not
Verify that the caller is authorized to perform the API operation, and return a 403 Forbidden error if not.
Verify the state of the application and return 409 Conflict if the operation would put the application into an inconsistent state
Verify the semantics of the request body and return a 422 Unprocessable Content error if the request is incomplete, inconsistent, or otherwise invalid
One pattern is to extend the API operations with a dry run feature. A dry run is a variant of the API operation which performs all (and only) the validation performed by the full operation, but does not execute the associated behavior. As such, it will return the same 400/401/403/409/422 that the full operation would return, allowing the client to highlight invalid form data or otherwise correct the problem. The client can use dry run operation incrementally as the user fills out a form, and disable the “Save” or “Submit” or similar UI controls if there are validation errors.
One way to implement a dry run is to create a separate "validation” operation for each API operation. This has the significant disadvantage of greatly increasing the footprint (size) of the API and adding a lot of duplication.
Rather than duplicate operations to add sibling validation operations, another approach is to add a ?dryRun=true query parameter to the operations. When used, the operation can return 204 No Content if the request contains no problems. The dryRun parameter acts as a “short circuit” in the API operation. The implementation performs the full validation it would normally do before executing the desired behavior, but then stops before actually executing anything other than the validation.
This pattern has a small impact on the API footprint compared to making sibling validation operations. A smaller footprint makes the API easier to read and understand. It is also a good use of the DRY principal, since you do not have to duplicate the definition of all the operation request parameters and request bodies, which opens up the chance for them to become out of sync.
Leave a calling card - by David Biesack
Make API responses more self-descriptive with reference objects
In OAS, a reference object contains a $ref value and may contain summary or description values. However, there is a kernel of usefulness here that can be used outside of defining an API with OpenAPI — we can use a construct inspired by OAS reference objects instead of terse and cryptic Restful JSON URLs or naked resource ID properties.
Such reference objects in API responses (or requests) can include other key identifying data about the referenced resource; these are optional and informative. The id or url of the resource are required to actually identify the referenced resource. This makes the overall JSON payload more self-descriptive and does not send the developer down ratholes trying to understand data they see when exploring and learning the API.
To make these reference objects even more useful, the API service can build them for you instead of making the client construct them. For example, the response from the getUniverse operation can contain a reference or ref property which is the reference object that the client can embed in other requests when citing a universe. The *Item schema in the API’s list responses (see “What am I getting out of this?”) can also include the reference object.
Registered & Protected by MarkMonitor
API Evangelist by The API Evangelist
Understanding the technology, business, policies, and people of Apis.
Bump CLI
This site contains the Bump.sh documentation, product updates descriptions, examples of how to use Bump.sh, as well as guides to help you build better REST APIs (OpenAPI) and event-driven architectures (AsyncAPI).
Real Estate API documentation
Real Estate API - Focused Specification
> OpenAPI specification for tailored for use with the {landrise.reapi} R package.
Endpoints
Includes specifications for the Real Esta...
Bump.sh Documentation
This site contains the Bump.sh documentation, product updates descriptions, examples of how to use Bump.sh, as well as guides to help you build better REST APIs (OpenAPI) and event-driven architectures (AsyncAPI).
Composing API Models with JSON Schema
Use JSON Schema effectively to build real API request and response bodies
This approach of defining tiny schemas, such as the chainLinkContentField, is a useful design pattern for keeping API definitions DRY. This is analogous to creating small, atomic, highly reusable functions in a programming language, rather than long, complex single-purpose functions.
If you find yourself repeating a property definition across multiple schemas, consider lifting that property into its own field definition schema. If there are groups of related properties that you use together in multiple schemas, you can group them together into a reusable {group}Fields schema (with a descriptive schema name that indicates its purpose, such as mutableChainLinkFields), then mix them into other schemas using the allOf schema composition construct.
This practice is one form of refactoring that is useful when defining and refining schemas.
Composition is not Inheritance
Warning: this JSON Schema composition construct is not inheritance… even if some tools translate this into inheritance in a target language. This means that, as the “allOf” name implies, all the schema constraints apply: you cannot override or replace constraints.
authorId: description: >- The ID of the author resource: who created this chain link. type: string minLength: 4 maxLength: 48 pattern: ^[-_a-zA-Z0-9:+$]{4,48}$ readOnly: true
Suppose we want to use schema composition but loosen those constraints in the chainLink schema’s authorId to allow 2 to 64 characters, we can express this as follows:
chainLink: title: A Chain Link allOf: - $ref: '#/components/schemas/chainLinkItem' - type: object properties: authorId: description: >- The ID of the author resource: who created this chain link. type: string minLength: 2 maxLength: 64 pattern: ^[-_a-zA-Z0-9:+$]{2,64}$ readOnly: false
However, we won’t get the desired effect. While the code generation may not change, the schema validation of a JSON object containing an authorId still enforces all of the subschema constraints. Thus, the effective schema constraints for the authorId property are the union of all the constraints:
type: string
minLength: 4
maxLength: 48
pattern: ^[-_a-zA-Z0-9:+$]{4,48}$
type: string
minLength: 2
maxLength: 64
pattern: ^[-_a-zA-Z0-9:+$]{2,64}$
While a value such as “C289D6F7-6B30-4788-9C70-4274730FAFCA” satisfies all 8 of these constraints, a shorter author ID string of 3 characters, “A00”, will fail the constraint #2 and #4, and thus that JSON would be rejected.
A final note on schema composition. The behavior of the allOf construct is well defined within JSON Schema for JSON validation. However, there is no standard for how this JSON schema construct must be treated in other tools such as code generation for client or server SDKs. Thus, each tool vendor (SmartBear’s swagger-codegen, the OSS openapi-generator, ApiMatic, Speakeasy, Fern, Kiota, etc.) may interpret JSON Schema in individual and different ways. It is useful to try them out to see if their interpretation and implementation meets your needs and expectations.
JSON Schema provides other keywords for schema composition (the oneOf, anyOf, and not keywords, as well as conditionals with a if/then/else construct) but these are more advanced topics and I’ve already asked too much of you to read this far. Stay tuned, however, there is more to come!
Validating API Requests
Techniques for API Request Validation
A promise of REST APIs is good decoupling of clients and services. This is achieved in part by reducing business logic as much as possible in the client application. For example, a client application may use a form for collecting information used in a POST operation to create an API resource, or to edit an existing resource before updating it with a PUT or PATCH operations. The client then maps the form fields to the properties of the operation’s request body. Clients can use front end frameworks and libraries to perform lots of low-level validation in the front end corresponding to JSON schema constraints
Forms which use required data fields for properties that are required in the JSON schema
using date pickers
checkboxes for selecting Boolean true or false values
drop down lists that allows selection from a list of fixed enum values
constrained numeric text entry
form fields that enforce a regular expression from a pattern constraint
However, this only covers “syntactic” or static field-level validation. Often, an API will also have business rules that the client must follow. Secure API services will enforce those business rules in the API operations
Parse the options and (JSON) request body and return a 400 Bad Request if any of the request data is malformed (i.e. does not satisfy the constraints of the operation (such as required body or required parameters) or all the JSON Schemas associated with the operation’s parameters or request body)
Verify that the caller passes valid Authorization to the API call, and return 401 Unauthorized if not
Verify that the caller is authorized to perform the API operation, and return a 403 Forbidden error if not.
Verify the state of the application and return 409 Conflict if the operation would put the application into an inconsistent state
Verify the semantics of the request body and return a 422 Unprocessable Content error if the request is incomplete, inconsistent, or otherwise invalid
One way to implement a dry run is to create a separate "validation” operation for each API operation. This has the significant disadvantage of greatly increasing the footprint (size) of the API and adding a lot of duplication.
Rather than duplicate operations to add sibling validation operations, another approach is to add a ?dryRun=true query parameter to the operations. When used, the operation can return 204 No Content if the request contains no problems. The dryRun parameter acts as a “short circuit” in the API operation. The implementation performs the full validation it would normally do before executing the desired behavior, but then stops before actually executing anything other than the validation.
This pattern has a small impact on the API footprint compared to making sibling validation operations. A smaller footprint makes the API easier to read and understand. It is also a good use of the DRY principal, since you do not have to duplicate the definition of all the operation request parameters and request bodies, which opens up the chance for them to become out of sync.
Your Guide to The Language of API Design
An overview of the articles in The Language of APIs series
APIwiz | Federated API Management
Unify, simplify, and manage your entire API ecosystem—bringing clarity, consistency, and control to every connection, all in one place.
Capacities – A studio for your mind
A powerful note-taking tool. All your ideas – typed and connected.
OpenTopography - Find Topography Data