Specs, Spec Testers, and Spec Writers - sgml/signature GitHub Wiki

Authors

How-to

APIs

specifications:
  - name: "AsyncAPI Specification"
    overview: >
      Begun as community‑driven npm implementations for asynchronous,
      event‑driven APIs, the AsyncAPI Specification formalizes a standardized
      way to document and build such APIs.
    governance: >
      Managed by the AsyncAPI Initiative, it emphasizes an open,
      community‑driven process without originating from one single organization.
    url: "https://www.asyncapi.com/"

  - name: "OpenAPI Specification (formerly Swagger)"
    overview: >
      Initially implemented via npm‑based tools as the Swagger specification,
      it evolved into the OpenAPI Specification—a formal definition for RESTful APIs
      that streamlines development and integration.
    governance: >
      Now maintained under the OpenAPI Initiative (sponsored by the Linux Foundation),
      it remains a community‑driven standard rather than a proprietary solution by a single organization.
    url: "https://www.openapis.org/"

  - name: "JSON:API"
    overview: >
      Emerging from practical npm‑based implementations, JSON:API provides a formal specification
      for building APIs in JSON, standardizing the way clients and servers communicate,
      and reducing boilerplate.
    governance: >
      It is maintained by a collaborative community committed to open standards.
    url: "https://jsonapi.org/"

  - name: "OpenRPC Specification"
    overview: >
      Arising from npm module implementations showcasing consistent approaches to JSON‑RPC,
      the OpenRPC Specification formalizes a standard for describing JSON‑RPC APIs,
      enabling better tooling like automatic documentation and code generation.
    governance: >
      Governed by the OpenRPC Initiative, it is a vendor‑neutral, community‑driven specification.
    url: "https://open-rpc.org/"

  - name: "Hydra Core Vocabulary"
    overview: >
      Originating through community experiments and npm‑based implementations focused on
      hypermedia‑driven API design in JSON‑LD, the Hydra Core Vocabulary offers formalized
      conventions for building interoperable hypermedia APIs.
    governance: >
      It is maintained through community consensus in a vendor‑neutral context,
      facilitating standardized hypermedia practices.
    url: "https://www.hydra-cg.com/"

xml_equivalents:
  - name: "AsyncAPI Specification"
    xml_equivalent: "WSDL 2.0 (for asynchronous SOAP operations)"
    notes: >
      AsyncAPI is focused on asynchronous, event‑driven APIs. While there is no direct XML format
      designed exclusively for asynchronous messaging in the XML world, WSDL 2.0 can describe asynchronous
      operations in SOAP-based services, making it the nearest analog.
    url: "https://www.w3.org/TR/wsdl20/"

  - name: "OpenAPI Specification"
    xml_equivalent: "WSDL"
    notes: >
      OpenAPI standardizes RESTful APIs (typically using JSON/YAML), whereas WSDL is the traditional XML‑based
      standard for describing SOAP web services. WSDL provides a formal XML contract for synchronous operations.
    url: "https://www.w3.org/TR/wsdl/"

  - name: "JSON:API"
    xml_equivalent: "OData (with AtomPub)"
    notes: >
      JSON:API formalizes a JSON-based approach for building APIs. In the XML realm, OData—with its support for
      AtomPub (an XML-based syndication format)—serves a similar role by defining data access and operations in a standard way.
      Although the approaches differ, they both aim to reduce boilerplate and standardize API interactions.
    url: "https://www.odata.org/"

  - name: "OpenRPC Specification"
    xml_equivalent: "XML-RPC"
    notes: >
      OpenRPC defines a standard for JSON‑RPC APIs, while XML‑RPC is its XML counterpart, specifying how remote procedure
      calls should be encoded in XML and transmitted over HTTP.
    url: "http://xmlrpc.scripting.com/spec.html"

  - name: "Hydra Core Vocabulary"
    xml_equivalent: "AtomPub / Collection+XML"
    notes: >
      Hydra provides a vocabulary for hypermedia‑driven REST APIs using JSON‑LD. In the XML ecosystem, similar hypermedia concepts
      have been implemented via protocols such as Atom Publishing Protocol (AtomPub) and Collection+XML for managing collections
      and representing hypermedia controls.
    url: "https://www.ietf.org/rfc/rfc5023.txt"

css_equivalents:
  - name: "CSS Houdini"
    overview: >
      A set of low-level APIs that allow developers to extend the CSS engine,
      enabling custom styling and layout capabilities that were once only possible
      through experimental code.
    notes: >
      Like community-driven API specs, Houdini emerged from developer needs to
      break free from the limitations of the core CSS language and is now being
      standardized with contributions from multiple vendors.
    url: "https://houdini.spec.whatwg.org/"

  - name: "CSS Grid Layout"
    overview: >
      A powerful layout system that lets developers create complex, responsive
      grid-based designs that adapt to different screen sizes.
    notes: >
      Originally developed via community experimentation and browser vendor
      prototypes, CSS Grid Layout is now a formal specification maintained
      by the W3C, paralleling the evolution from practical innovation to standardized spec.
    url: "https://www.w3.org/TR/css-grid-1/"

  - name: "CSS Flexbox"
    overview: >
      A one-dimensional layout method that provides an efficient way to align and
      distribute space among items in a container.
    notes: >
      Tested extensively by developers and incorporated into browser engines,
      Flexbox evolved from practice into a formal standard through community
      feedback and collaborative standardization.
    url: "https://www.w3.org/TR/css-flexbox-1/"

  - name: "CSS Custom Properties"
    overview: >
      Also known as CSS variables, these enable the reuse of values throughout
      stylesheet(s), supporting dynamic theming and more maintainable code.
    notes: >
      What began as an experimental feature widely adopted by developers
      was eventually standardized, reflecting the broader process of community-driven
      innovation leading to formal specification.
    url: "https://www.w3.org/TR/css-variables-1/"

Taxonomy / SDLC Modeling

Requirements / User Stories

Architecture Diagrams

Consultants

Organizations

Naming Conventions

Widgets

Bloggers

Log Formats

Standard Libraries

Standard Specifications

Patterns

Adoption Rates

Metadata Specifications

Standard Most Recent Specification Update Total Sections in Table of Contents GitHub Stars Wikidata URL
Schema.org November 22, 2024 12 sections 5.5k stars Schema.org
Microformats May 2010 8 sections 191 stars Microformats
XBRL January 14, 2025 14 sections 85 stars XBRL
OPML December 7, 2022 10 sections 3 stars OPML
application/opensearchdescription+xml January 7, 2021 6 sections 2 stars OpenSearch
XMPP January 2025 14 sections 687 stars XMPP
XForms January 2025 25 sections 87 stars XForms
GRDDL September 11, 2007 10 sections Not available GRDDL

Redundancy in Query Strings and the POST body

Advantage Explanation
Increased Visibility in Logs & Monitoring Query parameters are logged by web servers, making request patterns easily traceable without inspecting the request body.
Easier Manual Testing with Browsers & Tools Allows modifying URL parameters manually for quick debugging with a browser or Postman, without altering the request payload structure.
Redundancy for Fallback Handling Some frameworks prioritize query parameters if body parsing fails, ensuring data is accessible even in broken request flows.
Simplifies Mocking & Debugging with Logs Debugging proxy tools (e.g., Fiddler, Charles) can inspect query parameters even if the body is encrypted or compressed.
API Flexibility Across Systems Some APIs accept parameters both in the query string and body for easier client-side troubleshooting.
Potential Downsides Can cause confusion if query and body values conflict, expose sensitive data via query strings, and introduce unnecessary redundancy.

Strategy & Relevant RFCs

This approach leverages both URL query parameters and POST request bodies to improve debugging and flexibility. While query parameters provide visibility in server logs and quick troubleshooting options, the request body allows structured data handling.

Key specifications influencing this strategy:

  • RFC 7231 (HTTP/1.1 Semantics and Content) – Defines the behavior of HTTP POST and GET requests.
  • RFC 3986 (URI Generic Syntax) – Governs query strings in URLs.
  • RFC 7578 (Multipart Form Data Handling) – Important when mixing query parameters with form data in POST requests.
  • RFC 9110 (HTTP Semantics Updates) – Addresses modern HTTP usage, refining older RFCs.

By considering these standards, APIs and applications can ensure consistent behavior while maintaining flexibility for debugging purposes.

References