{"id":18698427,"url":"https://github.com/plurid/datasign","last_synced_at":"2025-11-08T17:30:33.516Z","repository":{"id":57137321,"uuid":"248194005","full_name":"plurid/datasign","owner":"plurid","description":"Single Source of Truth Data Contract Specifier","archived":false,"fork":false,"pushed_at":"2022-09-30T05:40:41.000Z","size":5340,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-14T11:51:41.115Z","etag":null,"topics":["data","file-format"],"latest_commit_sha":null,"homepage":"https://datasign.plurid.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plurid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-18T09:56:19.000Z","updated_at":"2022-09-30T05:40:47.000Z","dependencies_parsed_at":"2022-08-22T20:50:11.277Z","dependency_job_id":null,"html_url":"https://github.com/plurid/datasign","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plurid%2Fdatasign","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plurid%2Fdatasign/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plurid%2Fdatasign/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plurid%2Fdatasign/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plurid","download_url":"https://codeload.github.com/plurid/datasign/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239558934,"owners_count":19658934,"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":["data","file-format"],"created_at":"2024-11-07T11:28:18.299Z","updated_at":"2025-11-08T17:30:33.466Z","avatar_url":"https://github.com/plurid.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca target=\"_blank\" href=\"https://datasign.plurid.com\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/plurid/datasign/master/about/identity/datasign-logo.png\" height=\"250px\"\u003e\n    \u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca target=\"_blank\" href=\"https://github.com/plurid/datasign/blob/master/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/license-DEL-blue.svg?colorB=1380C3\u0026style=for-the-badge\" alt=\"License: DEL\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\n\n\u003ch1 align=\"center\"\u003e\n    datasign\n\u003c/h1\u003e\n\n\n\u003ch3 align=\"center\"\u003e\n    Single Source of Truth Data Contract Specifier\n\u003c/h3\u003e\n\n\n\n\u003cbr /\u003e\n\n\n\n`datasign` is a file format to describe data contract signatures to be used as a single source of (specified) truth to generate files for various pipelines.\n\nSupported specification targets:\n\n+ `GraphQL`\n+ `Protocol Buffers`\n+ `TypeScript`\n\n\n### Contents\n\n+ [A Web-Oriented Example](#a-web-oriented-example)\n+ [Usage](#usage)\n    + [Command-Line Interface](#command-line-interface)\n    + [One-Time Compilation](#one-time-compilation)\n    + [Programmatic](#programmatic)\n+ [Syntax](#syntax)\n    + [General](#general)\n    + [Annotating](#annotating)\n    + [Commenting](#commenting)\n    + [Importing](#importing)\n    + [Metas](#metas)\n+ [Types](#types)\n    + [Primitives](#primitives)\n    + [Defaults](#defaults)\n    + [Composed](#composed)\n+ [Annotations](#annotations)\n    + [Entity](#entity)\n    + [Field](#field)\n+ [Packages](#packages)\n+ [Codeophon](#codeophon)\n\n\n\n## A Web-Oriented Example\n\n```\n                                    Text.datasign\n                                        |\n    _________________________________________________________________________\n    |                                   |                                   |\n    to TypeScript                     to GraphQL                          to Protocol Buffers/gRPC\n    Text.ts                           Text.graphql                        Text.proto\n```\n\n\n``` datasign\n// Text.datasign\n\n/*\n * Text Documentation\n */\nText {\n    // type the `id` field to `ID` for GraphQL, and `string` for TypeScript/Protocol Buffers/gRPC\n    @graphql ID\n    id string\n\n    name string\n    value string\n    @graphql Int\n    characters number\n    public boolean\n\n    @graphql Date\n    @proto number\n    generatedAt Date // assumes Date is already defined somewhere else/globally\n    generatedBy User\n}\n\nUser {\n    id string\n    name string\n}\n```\n\n\n``` typescript\n// Text.ts\n\n/**\n * Text Documentation\n */\nexport interface Text {\n    id: string;\n    name: string;\n    value: string;\n    characters: number;\n    public: boolean;\n    generatedAt: Date;\n    generatedBy: User;\n}\n\nexport interface User {\n    id: string;\n    name: string;\n}\n```\n\n\n``` graphql\n# Text.graphql\n\n#\n# Text Documentation\n#\ntype Text {\n    id: ID!\n    name: String!\n    value: String!\n    characters: Int!\n    public: Boolean!\n    generatedAt: Date!\n    generatedBy: User!\n}\n\ntype User {\n    id: String!\n    name: String!\n}\n```\n\n\n``` proto\n// Text.proto\n\n/**\n * Text Documentation\n */\nmessage Text {\n    required string id = 1;\n    required string name = 2;\n    required string value = 3;\n    required number characters = 4;\n    required boolean public = 5;\n    required number generatedAt = 6;\n    required User generatedBy = 7;\n}\n\nmessage User {\n    required string id = 1;\n    required string name = 2;\n}\n```\n\n\n\n## Usage\n\n### Command-Line Interface\n\n```\nUsage: datasign \u003cfiles | directories...\u003e\n\nOptions:\n-v, --version                output the version number\n-t, --target \u003ctype\u003e          comma-separated compilation targets: typescript, graphql, proto (default: \"typescript,graphql,proto\")\n-o, --output \u003cpath\u003e          output directory path (default: \"./\")\n-r, --resolve \u003ctype\u003e         resolve the output path relative to the \"file\" directory, \"process\" directory, or \"flatten\" into the output path (default: \"file\")\n-m, --merge [name]           merge the output into a single file (named or not) for each target\n-c, --comments [value]       insert the comments into the target files (default: true)\n-s, --spacing \u003cvalue\u003e        indentation spacing to be used in the compiled files (default: \"4\")\n-p, --preserve [value]       preserve newline spacing of the \".datasign\" file (default: true)\n-g, --generated [value]      inject a header in each generated file mentioning the source (default: true)\n-d, --debug                  display compiling errors (default: false)\n-h, --help                   display help for command\n```\n\n\nFor scripting usage, run in the package\n\n``` bash\nnpm install @plurid/datasign\n```\n\nor\n\n``` bash\nyarn add @plurid/datasign\n```\n\nand add a script in `package.json`\n\n``` json\n// .json\n\n{\n    \"scripts\": {\n        \"datasign\": \"datasign /path/to/files\"\n    }\n}\n```\n\n\n### One-Time Compilation\n\nFor a simple compilation, create the `.datasign` files, e.g. `Message.datasign`:\n\n``` datasign\n// .datasign\n\nMessage {\n    id string\n    value string\n}\n```\n\nand run the command pointing to the files location\n\n``` bash\nnpx @plurid/datasign ./Message.datasign\n```\n\n\n### Programmatic\n\nFor programmatic usage, install the `@plurid/datasign` package with `npm` or `yarn` and use in a similar manner\n\n``` typescript\n// .ts\n\nimport {\n    DatasignLoader,\n} from '@plurid/datasign';\n\nasync function main() {\n    const datasignLoader = new DatasignLoader('/path/to/file');\n\n    const graphql = await datasignLoader.load('graphql');\n    // `graphql` contains the types string\n\n    const proto = await datasignLoader.load('proto');\n    // `proto` contains the messages string\n\n    const typescript = await datasignLoader.load('typescript');\n    // `typescript` contains the types namespace\n}\n\nmain();\n```\n\n\n\n## Syntax\n\n### General\n\nA `datasign` file uses the `.datasign` extension, is conventionally named using `PascalCase`, and is composed of one or more `Datasign Entities`.\n\nA `Datasign Entity` is constituted by a `Name`, and a pair of braces `{`, `}`, signifying the start, respectively, the end, of the `Datasign Fields` section.\n\nA `Datasign Field` is a `key type` pair, incremented with `2` or `4` spaces.\n\nEach `Datasign Field` should be on a new line.\n\n``` datasign\n// .datasign\n\nName {\n    namedKeyOne string\n    namedKeyTwo number\n}\n```\n\n\n### Annotating\n\nThe `Datasign Entities` and the `Data Fields` can be annotated using the `@` symbol.\n\nThe [annotations](#annotations) allow for target-specific alterations of the compiled files.\n\nEach `Datasign Annotation` should be on a new line.\n\n`Datasign Annotations` 'stack' on top of each other and affect the next available `Datasign Entity` or `Datasign Field`.\n\n\n### Commenting\n\nA comment is specified using the double slash (`//`) and can be on it's own line or either inlined.\n\nexample:\n\n``` datasign\n// .datasign\n\n// this is a valid comment\nMessage { // this is also valid\n    id string\n    // other fields\n}\n```\n\nFor documentation purposes the documentation comment symbols `/*` paired with `*/` can be used.\n\nexample:\n\n``` datasign\n// .datasign\n\n/*\n * Documentation for the Message Entity.\n */\n// this is a valid comment\nMessage { // this is also valid\n    /*\n     * Documentation for the id field.\n     */\n    id string\n    // other fields\n}\n```\n\n\n### Importing\n\nA `.datasign` file can import data signatures from another `.datasign` file. The import can be namespaced or extracted. The `.datasign` filename extension is not required in the import statement.\n\n``` datasign\n// a.datasign\nSomeData {\n    one string\n}\n```\n\n``` datasign\n// b.datasign\n\n// namespaced import\nimport A from ./path/to/a\n\n// extracted import\nimport {\n    SomeData\n} from ./path/to/a\n\nSomeOtherData {\n    two A.SomeData\n    three SomeData\n}\n```\n\n\n### Metas\n\nMetas allow the insertion of specific data for each individual target.\n\n``` datasign\n// .datasign\n\n!proto `\n    // this text will be inserted only in the compiled .proto file\n`\n\n!graphql `\n    # this text will be inserted only in the compiled .graphql file\n`\n\n!typescript `\n    // this text will be inserted only in the compiled .ts file\n`\n```\n\n\n\n## Types\n\n### Primitives\n\n+ `number`\n+ `boolean`\n+ `string`\n\n### Defaults\n\n+ `number` will default to:\n    + `Int` for `GraphQL`\n    + `int32` for `Protocol Buffers`\n    + `number` for `Typescript`\n\n+ `boolean` will default to:\n    + `Boolean` for `GraphQL`\n    + `bool` for `Protocol Buffers`\n    + `boolean` for `Typescript`\n\n+ `string` will default to:\n    + `String` for `GraphQL`\n    + `string` for `Protocol Buffers`\n    + `string` for `Typescript`\n\n### Composed\n\nA type can be composed with another using parantheses, `(` and `)`, and, `\u0026`, or, `|`, equal, `=`, operators.\n\n``` datasign\n// .datasign\n\nA {\n    b string\n}\n\nB = A \u0026 {\n    c string\n}\n\nC = A | B\n\nD = (A | B) \u0026 {\n    e string\n}\n```\n\n\n## Annotations\n\n\nAllowed `Datasign Entity` annotations:\n\n+ `graphql`\n+ `proto`\n+ `typescript`\n\nAllowed `Datasign Field` annotations:\n\n+ `graphql`\n+ `proto`\n+ `typescript`\n\n\n### Entity\n\n#### `@typescript`\n\n##### `export`\n\nTo export or no the compiled interface.\n\ndefault: `true`\n\nexample:\n\n``` datasign\n// .datasign\n@typescript export false\nMessage {\n    // fields\n}\n```\n\ncompiles to\n\n``` typescript\n// .ts\ninterface Message {\n    // fields\n}\n```\n\n\n#### `@graphql`\n\n##### `kind`\n\nThe `GraphQL` kind of the compiled `GraphQL` data structure.\n\nvalues: `type` | `input` | `type-input`\n\ndefault: `type`\n\nexample:\n\n``` datasign\n// .datasign\n@graphql kind input\nMessage {\n    // fields\n}\n```\n\nwhich is equivalent to\n\n``` datasign\n// .datasign\n@graphql input\nMessage {\n    // fields\n}\n```\n\ncompiles to\n\n``` graphql\n# .graphql\ninput Message {\n    # fields\n}\n```\n\nor multi-kind\n\n``` datasign\n// .datasign\n@graphql type-input\nMessage {\n    // fields\n}\n```\n\ncompiles to\n\n``` graphql\n# .graphql\n\ntype Message {\n    # fields\n}\n\ninput Message {\n    # fields\n}\n```\n\n\n\n### Field\n\n#### `@graphql`\n\n##### `type`\n\nThe `GraphQL` type of the compiled `GraphQL` field.\n\nexample:\n\n``` datasign\nMessage {\n    @graphql type ID\n    id string\n}\n```\n\nwhich is equivalent to\n\n``` datasign\nMessage {\n    @graphql ID\n    id string\n}\n```\n\ncompiles to\n\n``` graphql\ntype Message {\n    id: ID!\n}\n```\n\n\n##### `directive`\n\nAdds the directive to the `GraphQL` field. The directive needs to be provided in the `GraphQL` schema.\n\nexample:\n\n``` datasign\nMessage {\n    newField string\n\n    // the `deprecated` directive needs to be provided to the graphql schema\n    @graphql directive deprecated reason \"Use `newField`.\"\n    oldField string\n}\n```\n\ncompiles to\n\n``` graphql\ntype Message {\n    newField: String!\n    oldField: String! @deprecated(reason: \"Use `newField`.\")\n}\n```\n\n\n#### `@proto`\n\n##### `type`\n\nThe `Protocol Buffers` type of the compiled `Protocol Buffers` field.\n\nexample:\n\n``` datasign\nCount {\n    @proto type int64\n    value number\n}\n```\n\nwhich is equivalent to\n\n``` datasign\nCount {\n    @proto int64\n    value number\n}\n```\n\ncompiles to\n\n``` proto\nmessage Count {\n    required int64 value = 1;\n}\n```\n\n\n\n## Packages\n\n\u003ca target=\"_blank\" href=\"https://www.npmjs.com/package/@plurid/datasign\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/@plurid/datasign.svg?logo=npm\u0026colorB=1380C3\u0026style=for-the-badge\" alt=\"Version\"\u003e\n\u003c/a\u003e\n\n[@plurid/datasign-javascript][datasign-javascript] • `JavaScript`/`TypeScript` implementation\n\n[datasign-javascript]: https://github.com/plurid/datasign/tree/master/packages/datasign-javascript\n\n\n\u003ca target=\"_blank\" href=\"https://github.com/plurid/datasign/tree/master/packages/datasign-grammar/vscode\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/vscode-v.0.0.4-1380C3?style=for-the-badge\" alt=\"Version\"\u003e\n\u003c/a\u003e\n\n[@plurid/datasign-grammar][datasign-grammar] • grammar for text editors (syntax highlighting, syntax verification)\n\n[datasign-grammar]: https://github.com/plurid/datasign/tree/master/packages/datasign-grammar\n\n\n\n## [Codeophon](https://github.com/ly3xqhl8g9/codeophon)\n\n+ licensing: [delicense](https://github.com/ly3xqhl8g9/delicense)\n+ versioning: [αver](https://github.com/ly3xqhl8g9/alpha-versioning)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplurid%2Fdatasign","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplurid%2Fdatasign","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplurid%2Fdatasign/lists"}