{"id":17635960,"url":"https://github.com/mohawk2/sql-translator-parser-openapi","last_synced_at":"2025-03-30T03:43:10.786Z","repository":{"id":59149816,"uuid":"147149640","full_name":"mohawk2/SQL-Translator-Parser-OpenAPI","owner":"mohawk2","description":null,"archived":false,"fork":false,"pushed_at":"2021-01-28T15:35:38.000Z","size":111,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-05T06:14:23.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mohawk2.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-03T04:01:45.000Z","updated_at":"2021-03-13T17:22:44.000Z","dependencies_parsed_at":"2022-09-13T08:50:22.765Z","dependency_job_id":null,"html_url":"https://github.com/mohawk2/SQL-Translator-Parser-OpenAPI","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohawk2%2FSQL-Translator-Parser-OpenAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohawk2%2FSQL-Translator-Parser-OpenAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohawk2%2FSQL-Translator-Parser-OpenAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohawk2%2FSQL-Translator-Parser-OpenAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mohawk2","download_url":"https://codeload.github.com/mohawk2/SQL-Translator-Parser-OpenAPI/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246273515,"owners_count":20750904,"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","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-10-23T02:24:49.110Z","updated_at":"2025-03-30T03:43:10.768Z","avatar_url":"https://github.com/mohawk2.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nSQL::Translator::Parser::OpenAPI - convert OpenAPI schema to SQL::Translator schema\n\n# PROJECT STATUS\n\n| OS      |  Build status |\n|:-------:|--------------:|\n| Linux   | [![Build Status](https://travis-ci.org/mohawk2/SQL-Translator-Parser-OpenAPI.svg?branch=master)](https://travis-ci.org/mohawk2/SQL-Translator-Parser-OpenAPI) |\n\n[![CPAN version](https://badge.fury.io/pl/SQL-Translator-Parser-OpenAPI.svg)](https://metacpan.org/pod/SQL::Translator::Parser::OpenAPI) [![Coverage Status](https://coveralls.io/repos/github/mohawk2/SQL-Translator-Parser-OpenAPI/badge.svg?branch=master)](https://coveralls.io/github/mohawk2/SQL-Translator-Parser-OpenAPI?branch=master)\n\n# SYNOPSIS\n\n    use SQL::Translator;\n    use SQL::Translator::Parser::OpenAPI;\n\n    my $translator = SQL::Translator-\u003enew;\n    $translator-\u003eparser(\"OpenAPI\");\n    $translator-\u003eproducer(\"YAML\");\n    $translator-\u003etranslate($file);\n\n    # or...\n    $ sqlt -f OpenAPI -t MySQL \u003cmy-openapi.json \u003emy-mysqlschema.sql\n\n    # or, applying an overlay:\n    $ perl -MHash::Merge=merge -Mojo \\\n      -e 'print j merge map j(f($_)-\u003eslurp), @ARGV' \\\n        t/06-corpus.json t/06-corpus.json.overlay |\n      sqlt -f OpenAPI -t MySQL \u003emy-mysqlschema.sql\n\n# DESCRIPTION\n\nThis module implements a [SQL::Translator::Parser](https://metacpan.org/pod/SQL::Translator::Parser) to convert\na [JSON::Validator::OpenAPI::Mojolicious](https://metacpan.org/pod/JSON::Validator::OpenAPI::Mojolicious) specification to a [SQL::Translator::Schema](https://metacpan.org/pod/SQL::Translator::Schema).\n\nIt uses, from the given API spec, the given \"definitions\" to generate\ntables in an RDBMS with suitable columns and types.\n\nTo try to make the data model represent the \"real\" data, it applies heuristics:\n\n- to remove object definitions considered non-fundamental; see\n[\"definitions\\_non\\_fundamental\"](#definitions_non_fundamental).\n- for definitions that have `allOf`, either merge them together if there\nis a `discriminator`, or absorb properties from referred definitions\n- creates object definitions for any properties that are an object\n- creates object definitions for any properties that are an array of simple\nOpenAPI types (e.g. `string`)\n- creates object definitions for any objects that are\n`additionalProperties` (i.e. freeform key/value pairs), that are\nkey/value rows\n- absorbs any definitions that are in fact not objects, into the referring\nproperty\n- injects foreign-key relationships for array-of-object properties, and\ncreates many-to-many tables for any two-way array relationships\n\n# ARGUMENTS\n\n## snake\\_case\n\nIf true, will create table names that are not the definition names, but\ninstead the pluralised snake\\_case version, in line with SQL convention. By\ndefault, the tables will be named after simply the definitions.\n\n# PACKAGE FUNCTIONS\n\n## parse\n\nStandard as per [SQL::Translator::Parser](https://metacpan.org/pod/SQL::Translator::Parser). The input $data is a scalar\nthat can be understood as a [JSON::Validator\nspecification](https://metacpan.org/pod/JSON::Validator#schema).\n\n## defs2mask\n\nGiven a hashref that is a JSON pointer to an OpenAPI spec's\n`/definitions`, returns a hashref that maps each definition name to a\nbitmask. The bitmask is set from each property name in that definition,\naccording to its order in the complete sorted list of all property names\nin the definitions. Not exported. E.g.\n\n    # properties:\n    my $defs = {\n      d1 =\u003e {\n        properties =\u003e {\n          p1 =\u003e 'string',\n          p2 =\u003e 'string',\n        },\n      },\n      d2 =\u003e {\n        properties =\u003e {\n          p2 =\u003e 'string',\n          p3 =\u003e 'string',\n        },\n      },\n    };\n    my $mask = SQL::Translator::Parser::OpenAPI::defs2mask($defs);\n    # all prop names, sorted: qw(p1 p2 p3)\n    # $mask:\n    {\n      d1 =\u003e (1 \u003c\u003c 0) | (1 \u003c\u003c 1),\n      d2 =\u003e (1 \u003c\u003c 1) | (1 \u003c\u003c 2),\n    }\n\n## definitions\\_non\\_fundamental\n\nGiven the `definitions` of an OpenAPI spec, will return a hash-ref\nmapping names of definitions considered non-fundamental to a\nvalue. The value is either the name of another definition that _is_\nfundamental, or or `undef` if it just contains e.g. a string. It will\ninstead be a reference to such a value if it is to an array of such.\n\nThis may be used e.g. to determine the \"real\" input or output of an\nOpenAPI operation.\n\nNon-fundamental is determined according to these heuristics:\n\n- object definitions that only have one property (which the author calls\n\"thin objects\"), or that have two properties, one of whose names has\nthe substring \"count\" (case-insensitive).\n- object definitions that have all the same properties as another, and\nare not the shortest-named one between the two.\n- object definitions whose properties are a strict subset of another.\n\n# OPENAPI SPEC EXTENSIONS\n\n## `x-id-field`\n\nUnder `/definitions/$defname`, a key of `x-id-field` will name a\nfield within the `properties` to be the unique ID for that entity.\nIf it is not given, the `id` field will be used if in the spec, or\ncreated if not.\n\nThis will form the ostensible \"key\" for the generated table. If the\nkey used here is an integer type, it will also be the primary key,\nbeing a suitable \"natural\" key. If not, then a \"surrogate\" key (with a\ngenerated name starting with `_relational_id`) will be added as the primary\nkey. If a surrogate key is made, the natural key will be given a unique\nconstraint and index, making it still suitable for lookups. Foreign key\nrelations will however be constructed using the relational primary key,\nbe that surrogate if created, or natural.\n\n## `x-view-of`\n\nUnder `/definitions/$defname`, a key of `x-view-of` will name another\ndefinition (NB: not a full JSON pointer). That will make `$defname`\nnot be created as a table. The handling of creating the \"view\" of the\nrelevant table is left to the CRUD implementation. This gives it scope\nto use things like the current requesting user, or web parameters,\nwhich otherwise would require a parameterised view. These are not widely\navailable.\n\n## `x-artifact`\n\nUnder `/definitions/$defname/properties/$propname`, a key of\n`x-artifact` with a true value will indicate this is not to be stored,\nand will not cause a column to be created. The value will instead be\nderived by other means. The value of this key may become the definition\nof that derivation.\n\n## `x-input-only`\n\nUnder `/definitions/$defname/properties/$propname`, a key of\n`x-input-only` with a true value will indicate this is not to be stored,\nand will not cause a column to be created. This may end up being merged\nwith `x-artifact`.\n\n# DEBUGGING\n\nTo debug, set environment variable `SQLTP_OPENAPI_DEBUG` to a true value.\n\n# AUTHOR\n\nEd J, `\u003cetj at cpan.org\u003e`\n\n# LICENSE\n\nCopyright (C) Ed J\n\nThis library is free software; you can redistribute it and/or modify\nit under the same terms as Perl itself.\n\n# SEE ALSO\n\n[SQL::Translator](https://metacpan.org/pod/SQL::Translator).\n\n[SQL::Translator::Parser](https://metacpan.org/pod/SQL::Translator::Parser).\n\n[JSON::Validator::OpenAPI::Mojolicious](https://metacpan.org/pod/JSON::Validator::OpenAPI::Mojolicious).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohawk2%2Fsql-translator-parser-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmohawk2%2Fsql-translator-parser-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohawk2%2Fsql-translator-parser-openapi/lists"}