Skip to main content

Import

Summary#

sysl import generates a Sysl spec file from some other specification format. This is a useful tool for:

  • Migration: convert another format into Sysl, and continue working with that Sysl spec as your new single source of truth.
  • Consistency: validate that another source of truth has not diverged from a previously imported spec.
  • Compatibility: feed the result of import into another Sysl tool.

Usage#

sysl import --input=<FILE-TO-IMPORT.EXT> --app-name=<APP-NAME> [<flags>]

Currently, the supported formats include:

  • OpenAPI 2.0 (fka Swagger)
  • OpenAPI 3.0
  • XSD
  • Avro (Kafka)
  • SQL (Spanner, PostgreSQL, MySQL, BigQuery)
  • A directory of SQL migration scripts
  • Protobuf
  • A directory of Protobuf files

Required Flags#

Universal#

  • -i, --input=<FILE-TO-IMPORT.EXT>: Input filename.
  • -a, --app-name=<APP-NAME>: Name of the sysl app to define in sysl model.

Protobuf#

  • -I, --import-paths="foo,bar/baz": The directories to resolve imports in.

Optional flags#

  • -f, --format=FORMAT: Explicit format of the input file. This is only needed if it cannot be auto-detected (e.g. a particular dialect of SQL).
  • -p, --package=PACKAGE: Name of the Sysl package to define in the Sysl model.
  • -o, --output="output.sysl": Output filename. If not provided, the output will be sent to stdout.

More common optional flags

Examples#

OpenAPI#

Command line

sysl import --input=simple-api.yaml --app-name=Simple --output=simple-api.sysl
Input OpenAPI file: simple-api.yaml
openapi: "3.0"info:  title: Simple  description: Simple demo for openapi file importpaths:  /test/:    get:      description: Endpoint for testing GET      responses:        200:          description: "200 OK"          content:            application/json:              schema:                $ref: "#/components/schemas/SimpleObj"        500:          $ref: "#/components/responses/500Response"components:  schemas:    SimpleObj:      type: object      properties:        name:          type: string    SimpleObj2:      type: object      properties:        name:          type: SimpleObj  responses:    500Response:      description: Internal Server Error      schema:        $ref: "#/components/schemas/SimpleObj"
Output Sysl file: simple-api.sysl
############################################                                      ####  AUTOGENERATED CODE -- DO NOT EDIT!  ####                                      ############################################
Simple "Simple":    @description =:        | Simple demo for openapi file import
    /test:        GET:            | Endpoint for testing GET            return error            return ok <: SimpleObj
    #---------------------------------------------------------------------------    # definitions
    !type SimpleObj:        name <: string?:            @json_tag = "name"
    !type SimpleObj2:        name <: SimpleObj?:            @json_tag = "name"

Swagger#

Command line

sysl import --input=simple-swagger.yaml --app-name=Simple --output=simple-swagger.sysl
Input Swagger file: simple-swagger.yaml
swagger: "2.0"info:  title: Simple  description: Simple demo for swagger file importpaths:  /test:    get:      description: Endpoint for testing GET      responses:        200:          description: 200 OK          schema:            $ref: "#/definitions/SimpleObj"definitions:  SimpleObj:    type: object    properties:      name:        type: string
Output Sysl file: simple-swagger.sysl
############################################                                      ####  AUTOGENERATED CODE -- DO NOT EDIT!  ####                                      ############################################
Simple "Simple":    @description =:        | Simple demo for swagger file import
    /test:        GET:            | Endpoint for testing GET            return ok <: SimpleObj
    #---------------------------------------------------------------------------    # definitions
    !type SimpleObj:        name <: string?:            @json_tag = "name"

XSD#

Command line

sysl import --input=simple-xsd.xsd --app-name=Simple --output=simple-xsd.sysl
Input XSD file: simple-xsd.xsd
<?xml version="1.0"?><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">    <xs:complexType name="User">        <xs:sequence>            <xs:element name="id" type="xs:string" minOccurs="1" maxOccurs="1"/>            <xs:element name="name" type="xs:string" minOccurs="0" maxOccurs="10"/>        </xs:sequence>    </xs:complexType></xs:schema>
Output Sysl file: simple-xsd.sysl
############################################                                      ####  AUTOGENERATED CODE -- DO NOT EDIT!  ####                                      ############################################
Simple:    @description =:        | No description.
    #---------------------------------------------------------------------------    # definitions
    !type User:        id(1..1) <: string:            @json_tag = "id"        name(0..10) <: sequence of string?:            @json_tag = "name"

Spanner migration directory#

sysl import --input=sysl/pkg/importer/spanner/test --app-name=Foo
############################################                                      ####  AUTOGENERATED CODE -- DO NOT EDIT!  ####                                      ############################################
Foo [spanner_spec="1.0"]:    !table foo:        a <: int? [~pk]

Protobuf#

sysl import --input=pkg/importer/proto/tests/proto2.proto --app-name=Foo --output=pkg/importer/proto/tests/combined/proto2.sysl --import-paths=pkg/importer/proto/tests/

Protobuf directory#

sysl import --input=pkg/importer/proto/tests/combined/ --app-name=Foo --output=pkg/importer/proto/tests/combined/combined.sysl --import-paths=pkg/importer/proto/tests/combined --format=ProtobufDir