{"id":22382027,"url":"https://github.com/googleinterns/spec-math","last_synced_at":"2025-07-31T03:30:43.266Z","repository":{"id":38489707,"uuid":"267638148","full_name":"googleinterns/spec-math","owner":"googleinterns","description":null,"archived":true,"fork":false,"pushed_at":"2023-10-11T07:11:12.000Z","size":2189,"stargazers_count":4,"open_issues_count":5,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-06-03T00:35:14.834Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googleinterns.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-28T16:19:47.000Z","updated_at":"2025-05-01T12:16:38.000Z","dependencies_parsed_at":"2025-06-02T13:07:15.743Z","dependency_job_id":"8c9e014f-b970-459c-92f2-1dcd329e3170","html_url":"https://github.com/googleinterns/spec-math","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/googleinterns/spec-math","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fspec-math","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fspec-math/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fspec-math/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fspec-math/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googleinterns","download_url":"https://codeload.github.com/googleinterns/spec-math/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fspec-math/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267983362,"owners_count":24176056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-05T00:11:32.896Z","updated_at":"2025-07-31T03:30:42.847Z","avatar_url":"https://github.com/googleinterns.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./app/src/assets/img/specmath_logo.svg\" width=\"350\" title=\"Spec Math logo\"\u003e\n\u003c/p\u003e\n\n---\n\n## Spec Math\n## Overview\nSpec Math is a platform for performing operations on OpenAPI specifications. \n[OpenAPI](https://github.com/OAI/OpenAPI-Specification) is an industry-standard\nformat for machine-readable REST API descriptions.\n\n## About this document\nThis document contains an overview of this repository as well as a description of Spec Math.\n\nA goal of this document is to highlight the capabilities of Spec Math and\ndescribe its operations and functions so that you can determine if it might be useful to your project. \n\nWhile this repository already contains a [Java implementation](library) of Spec Math, we acknowledge that\nyour project might have different language needs and hope that this document (along with the\n[Java implementation](library)) will also provide\nenough information such that you could implement Spec Math in any language\nof your choosing. For more specific documentation and installation instructions, please look \nat the respective folder in the directory structure\ndescribed below.\n\n## Directory structure\n- The [library](library) folder contains the \"Spec Math Library\", an implementation of Spec Math in Java.\n- The [web](web) folder showcases an example usage of the Spec Math Library through an API which is connected\n to the frontend application in the\n[app](app) folder.\n\n## Spec Math and the Spec Math Library\n\n### Background\nSpecifications play a critical role in the API lifecycle. They can enforce a contract between client\nand server teams, easily generate documentation and client libraries, reduce the work of\ncreating a proxy for an existing service and much more. The\nSpec Math project aims to afford even more power to API developers who use the OpenAPI\nspecification. The [Spec Math Library](library) will enable them to do the following:\n\n- Merge two (or more in a future update) OpenAPI specifications into one.\n- Filter an OpenAPI specification into a new spec based on specified criteria.\n- Overlay an OpenAPI specification by superimposing partial specs with domain-specific annotations.\n- And more, discussed in the sections and examples below.\n\nWhile these features are currently supported in the [Spec Math Library](library), please\nnote that \"Spec Math\" as a platform could theoretically support many other operations on OpenAPI specifications.\nContributions of new features and operations are welcome!\n\nBelow is a simple example of a use case of Spec Math.\n\nLet's suppose there is a complex project with several teams working on it. \nEach team is responsible for developing different\nportions of an API. These teams might include marketing, inventory, analytics, and others. If all\nteams were to work off of the same specification, it could become an extremely long and\nunwieldy document. Then, if the developers want to expose a subset of functionality to specific\nuser groups and developer teams, they would perform a tedious, manual, and error-prone\ncherry-pick of features to add to a new spec. These are some examples of where Spec Math could\ncome to the rescue.\n\n#### Union\nOne feature of Spec Math is to merge two or more specs into one. The developers could\nthen have each team working on their own APIs with their own respective specs. From there, the\ndevelopers can leverage the [Spec Math Library](library) to create a unified spec to describe the APIs\ndeveloped across all the teams.\n\n#### Filter\nThe developers are now able to unify the specs across multiple teams using the union feature\nof the Spec Math Library. Now, though, providers want to give specific user groups and\ndeveloper teams access to portions of the unified API. For example, the developers now want to\ncreate a public API with all of the API endpoints across all teams that do not require\ninternal authentication. It would be a tedious and error-prone process to manually cherry-pick pieces of\nthe unified API and paste them into a new public API spec.\nWith filtering, the developers can provide the unified spec, along with a list of filter criteria that\nthey want to match, and get a new spec matching the criteria. For example, filtering would allow the developers\nto generate a new spec with only the \"public\" tagged operations.\n\n#### Overlay\nOverlay allows developers to place OpenAPI spec fragments on top of existing specs.\n\nFor example, in the case of both filtering and merging, the resultant spec represents a different API product\nthan the input specs. This is why overlaying functionality will also be supported. An overlay can\nbe applied using a “default file” which contains metadata about the final API product that is\nproduced from Spec Math operations. For example, if a company wishes to build a web\napplication using filtered pieces of their unified API, the original spec will no longer have an\naccurate `info: title` key path. The overlay will contain something like `info: title: Company Web\nApplication` which will be applied to the resultant specification. Another example is to have overlays\ncreated for different stages in the lifecycle as an API moves from pre production to production.\n\n### Overview\n\nThis section provides descriptions of Spec Math operations. See the background section for an example of how\nsome of these capabilities of Spec Math might be useful.   \n\nFor additional specific examples of each operation described below, please take a look at the integration\ntests for the [Spec Math Library](library/src/test/java/org/specmath/library/SpecMathTest.java). Tests are\nprovided for some example usages of the operations discussed below. Each test contains a sample input and output.\n\n#### Operations\n\n##### Union\n\n##### Union Of Two Specs\nUnion of two specs takes specs A and B along with an optional set of rules to create a new spec C which contains A and B.\n\nA collision (or union conflict) occurs when two YAML key paths have different primitive values. For example, if\nspec A had `info: license: name: MIT` and spec B had `info: license: name: GPL`, there would be\na conflict in the `info: license: name` key path. To resolve this, the user can provide a defaults\nfile as an overlay. In cases where the overlay cannot resolve the conflict, the conflicting key\npaths will be reported back. The user can then resolve the conflicts by either:\n\n- using a conflict resolution file ([sample](library/src/test/resources/conflictMerged.yaml)) passed in as a parameter to the union,\n- manually resolving the specs by removing the conflict\n- or updating the defaults file.\n\n##### Union Of Multiple Specs\nUnion of multiple specs takes a list of specs L along with an optional set of rules to create a new spec\nwhich contains all specs in L.\n\nA collision (or union conflict) occurs when a YAML key path has several possible options across two\nor more specs. The example from \"Union of Two Specs\" is the same, except that conflicts can occur\nacross more than just two specs. The methods to resolve conflicts are also the same.\n\n#### Overlay\nOverlay takes spec A along with a defaults file D ([sample](library/src/test/resources/metadata.yaml)) to modify spec A. D is a spec fragment\nwhich will be placed \"on top\" of spec A. \nIn the case of a would-be collision, the defaults file takes priority. \nAn overlay operation is a specialized Union operation between A and D where D will always take priority.\nTherefore, Overlay operations will not have union conflicts. \n\n#### Filter\nFiltering takes spec A along with a filter file F to create a new spec B which contains a subset\nof features from A according to F. A filter file contains a list of Filter Criteria Objects, discussed below.\nOnly the component references from A which are relevant to B will be included.\n\nBelow is a list of properties which can be added to a Filter Criteria Object. A filter file F is a list of\nFilter Criteria Objects. For examples of F, please see the JSON files in the [filtering tests resources directory](library/src/test/resources/filtering).\n\n- **FILTER BY TAGS**. The user can achieve fine-grained filtering functionality extremely\neasily by just adding specific tags to the spec. For example, the user could mark\noperations as “internal” or “external” and easily filter based on these tags.\n  - Users can provide a list of tags in the `tags` property of the filter criteria.\n   Only endpoints\n   which contain those tags will be\nkept in the resultant spec. \n  - Users can specify certain tags with the `removableTags` property\nin the filter criteria, which will remove those tags in the resultant\nspec. That way, published spec docs wouldn’t contain\nthese special tags which were only added to the spec for the purposes of\nfiltering. \n- **FILTER BY PATHS AND OPERATIONS**. The user can filter based on desired paths,\n as well as desired operations (e.g. get, put)\n  - Paths are specified in the `path` property in the filter criteria\n  - Operations are specified in the `operations` property in the filter criteria\n  \nIn addition to a filter file, users can also specify other filtering “options” or “parameters”. Similar\nto the union operation, the API product which is represented by the result of a filter operation is\nquite different from the spec which was used to filter. Therefore, a useful option will be to\nprovide metadata about the resultant spec. \n\nBy default, when the user provides a list of filter criteria, all matches\nwill be included. Future work includes the ability to provide an “exclude” option, which will exclude\npaths matching the criteria in the resultant spec.\n\n## Disclaimer\nThis is not an officially supported Google Product. Any enhancement requests or bugs should only be reported via issues on this project. \n\n## Copyright\n\nCopyright 2020, Google LLC.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleinterns%2Fspec-math","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogleinterns%2Fspec-math","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleinterns%2Fspec-math/lists"}