{"id":22750044,"url":"https://github.com/pwall567/json-kotlin-gradle","last_synced_at":"2025-04-14T12:53:00.525Z","repository":{"id":41296919,"uuid":"356311679","full_name":"pwall567/json-kotlin-gradle","owner":"pwall567","description":"Gradle JSON Schema code generation plugin","archived":false,"fork":false,"pushed_at":"2025-04-13T13:36:32.000Z","size":209,"stargazers_count":17,"open_issues_count":8,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T14:35:08.547Z","etag":null,"topics":["gradle-plugin","json-schema","kotlin"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pwall567.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2021-04-09T15:10:54.000Z","updated_at":"2025-04-13T13:36:15.000Z","dependencies_parsed_at":"2024-02-08T15:53:48.932Z","dependency_job_id":"924cf132-2733-4f92-9e99-a05e9ff4dbd9","html_url":"https://github.com/pwall567/json-kotlin-gradle","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwall567%2Fjson-kotlin-gradle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwall567%2Fjson-kotlin-gradle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwall567%2Fjson-kotlin-gradle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwall567%2Fjson-kotlin-gradle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pwall567","download_url":"https://codeload.github.com/pwall567/json-kotlin-gradle/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248885337,"owners_count":21177623,"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":["gradle-plugin","json-schema","kotlin"],"created_at":"2024-12-11T04:11:49.317Z","updated_at":"2025-04-14T12:53:00.512Z","avatar_url":"https://github.com/pwall567.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# json-kotlin-gradle\n\n[![Build Status](https://github.com/pwall567/json-kotlin-gradle/actions/workflows/build.yml/badge.svg)](https://github.com/pwall567/json-kotlin-gradle/actions/workflows/build.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Kotlin](https://img.shields.io/static/v1?label=Kotlin\u0026message=v2.0.21\u0026color=7f52ff\u0026logo=kotlin\u0026logoColor=7f52ff)](https://github.com/JetBrains/kotlin/releases/tag/v2.0.21)\n[![Maven Central](https://img.shields.io/maven-central/v/net.pwall.json/json-kotlin-gradle?label=Maven%20Central)](https://central.sonatype.com/artifact/net.pwall.json/json-kotlin-gradle)\n\nGradle JSON Schema code generation plugin.\n\n## NEW\n\nThe means of specifying input files to the generation process has been extended; see the [`inputs`](#inputs) section.\n\n## Background\n\nThe [`json-kotlin-schema-codegen`](https://github.com/pwall567/json-kotlin-schema-codegen) project provides a means of\ngenerating Kotlin or Java classes (or TypeScript interfaces) from [JSON Schema](https://json-schema.org/) object\ndescriptions.\nThe `json-kotlin-gradle` plugin simplifies the use of this code generation mechanism from the\n[Gradle Build Tool](https://gradle.org/).\n\n## To Use\n\nInclude the following at the start of your `build.gradle.kts` file:\n```kotlin\nimport net.pwall.json.kotlin.codegen.gradle.JSONSchemaCodegenPlugin\nimport net.pwall.json.kotlin.codegen.gradle.JSONSchemaCodegen // only required if \"configure\" block included\n\nbuildscript {\n    repositories {\n        mavenCentral()\n    }\n    dependencies {\n        classpath(\"net.pwall.json:json-kotlin-gradle:0.119\")\n    }\n}\n\napply\u003cJSONSchemaCodegenPlugin\u003e()\n```\nThe `apply` line should come after the `buildscript` block, and **before** any `configure` block (see below).\n\nAnd to have the generated source files compiled:\n```kotlin\nsourceSets.main {\n    java.srcDirs(\"build/generated-sources/kotlin\")\n}\n```\nThis shows the use of the default output directory; if it is changed by the use of the [`outputDir`](#outputdir)\nconfiguration property, this setting will also change.\nThe `srcDirs` function takes a `vararg` list; if other source files are to be included in the compilation task the\ndirectories may be added to the function call.\n\nThe plugin follows the principle of \u0026ldquo;convention over configuration\u0026rdquo;.\nThe default location for the schema file or files to be input to the generation process is:\n```\n    «project root»/src/main/resources/schema\n```\nand the default location for the\n[config file](https://github.com/pwall567/json-kotlin-schema-codegen/blob/main/CONFIG.md) (if required) is:\n```\n    «project root»/src/main/resources/codegen-config.json\n```\nIf your files are in these default locations, the above additions to `build.gradle.kts` will be all you will need.\n\nIf you wish to specify the location of your schema or config files, or if you wish to use any of the other plugin\ncustomisation options, you may include a configuration block as follows:\n```kotlin\nconfigure\u003cJSONSchemaCodegen\u003e {\n    configFile.set(file(\"path/to/your/config.json\")) // if not in the default location\n    packageName.set(\"your.package.name\") // if not specified in a config file\n    generatorComment.set(\"comment...\")\n    inputs {\n        inputFile(file(\"path/to/your/schema/file/or/files\")) // if not in the default location\n        inputFile {\n            file.set(file(\"path/to/your/schema/file/or/files\")) // alternative syntax for above\n        }\n        inputComposite {\n            file.set(file(\"path/to/your/schema/composite/file\"))\n            pointer.set(\"/\\$defs\") // a JSON Pointer to the group of definitions within the file\n        }\n        inputURI(uri(\"https://example.com/path/to/file\"))\n        inputCompositeURI(uri(\"https://example.com/path/to/composite\"), \"\\$defs\")\n        // inputFile, inputComposite, inputURI and inputCompositeURI\n        // may be repeated as necessary in any combination\n    }\n    classMappings { // configure specific class mappings if required\n        byFormat(\"java.time.Duration\", \"duration\")\n    }\n    schemaExtensions { // configure extension keyword uses if required\n        patternValidation(\"x-type\", \"account-number\", Regex(\"^[0-9]{4,10}$\"))\n    }\n}\n```\n\nIf any setting in this configuration block conflicts with the equivalent setting in the config file, this configuration\nblock (in `build.gradle.kts`) takes precedence.\n\n## Configuration Options\n\n### `inputs`\n\nThe `inputs` section specifies the location(s) of the input files.\nBy default, the plugin will process all files in the `src/main/resources/schema` directory (and subdirectories);\nto specify a different location or a combination of inputs, the `inputs` section allows multiple `inputFile` or\n`inputComposite` definitions.\n\n### `inputFile`\n\nThis specifies an individual file or directory of files to be added to the list of files to be processed.\n```kotlin\n    inputs {\n        inputFile {\n            file.set(file(\"path/to/your/schema/file/or/files\"))\n            subPackage.set(\"sub.package.name\") // optional sub-package name\n        }\n        inputFile(file(\"path/to/your/schema/file/or/files\")) // alternative syntax\n        inputFile(file(\"path/to/your/schema/file/or/files\"), \"sub.package.name\") // alternative syntax\n    }\n```\nIf a `subPackage` name is supplied, the class or classes generated from this `inputFile` declaration will be output to\nthe package _base.subPackage_ where _base_ is the base package from the [`packageName`](#packagename) declaration or the\nconfig file, and _subPackage_ is the name given here.\nThe name may be a single name or a structured name using dot separators.\n\nAs many `inputFile` entries as are required may be specified, and they may be combined with other forms of input\nspecification.\n\n### `inputComposite`\n\nOne of the common uses of the code generator is to generate a set of classes from a composite file.\nFor example, an OpenAPI file may contain a number of schema definitions for the request and response objects of the API,\nor a JSON Schema file may contain a set of definitions in the `$defs` section.\n\nTo specify this type of usage:\n```kotlin\n    inputs {\n        inputComposite {\n            file.set(file(\"path/to/your/composite/file\"))\n            pointer.set(\"/\\$defs\")\n            include.set(listof(\"IncludeThis\", \"AndThis\")) // optional - specifies classes to include\n            exclude.set(listof(\"NotThis\", \"NorThis\")) // optional - sepcifies files to exclude\n        }\n        inputComposite(file.set(file(\"path/to/your/composite/file\")), \"\\$defs\") // alternative syntax\n    }\n```\nAs many `inputComposite` entries as are required may be specified, and they may be combined with other forms of input\nspecification.\n\n### `inputURI`\n\nMany organisations will make their schema files available via a public URL.\nOthers will have a local schema repository accessible within their own VPN.\nThe code generator can generate files directly from a URI:\n```kotlin\n    inputs {\n        inputURI {\n            uri.set(uri(\"https://local.domain.com/schema/customer.json\"))\n        }\n        inputURI(uri(\"https://local.domain.com/schema/customer.json\")) // alternative syntax\n    }\n```\nIn this case, the URI must be a valid URL pointing to a downloadable file.\n\nAs many `inputURI` entries as are required may be specified, and they may be combined with other forms of input\nspecification.\n\n### `inputCompositeURI`\n\nComposite files may also be accessed by URI:\n```kotlin\n    inputs {\n        inputCompositeURI {\n            uri.set(uri(\"https://local.domain.com/schema/api.json\"))\n            pointer.set(\"/\\$defs\")\n            include.set(listof(\"IncludeThis\", \"AndThis\")) // optional - specifies classes to include\n            exclude.set(listof(\"NotThis\", \"NorThis\")) // optional - sepcifies files to exclude\n        }\n        inputCompositeURI(uri(\"https://local.domain.com/schema/api.json\"), \"\\$defs\") // alternative syntax\n    }\n```\nThe URI must be a valid URL pointing to a downloadable file, and the pointer string must select a sub-tree within that\nfile.\nTo include two separate sections of the same file, include two separate `inputCompositeURI` entries with the same URI\nbut different pointers (and possibly include/exclude settings).\n\nAs many `inputCompositeURI` entries as are required may be specified, and they may be combined with other forms of input\nspecification.\n\n### `include` and `exclude`\n\nTo include only a nominated subset of definitions from a combined file (using [`inputComposite`](#inputcomposite) or\n[`inputCompositeURI`](#inputcompositeuri)), specify the names of the definitions to be included (optional \u0026ndash; see\nexample above).\n\nAlternatively, to exclude nominated definitions from a combined file, specify the names of the definitions to be\nexcluded.\n\nIf both `include` and `exclude` are supplied for the same composite, both will be applied, but this clearly\ndoesn\u0026rsquo;t make a great deal of sense since in order to be excluded, a definition must first have been explicitly\nincluded.\n\nThe alternative (shorter) syntax for `inputComposite` or `inputCompositeURI` does not provide for the specification of\n`include` or `exclude`.\n\n### `configFile`\n\nIf the config file is not in the default location of `src/main/resources/codegen-config.json`, the location of the file\nmay be specified using the `configFile` property:\n```kotlin\n    configFile.set(file(\"path/to/your/config.json\"))\n```\n\n### `inputFile`\n\nThis is the earlier means of specifying the input file or files;\nthe [`inputs`](#inputs) section above is more flexible, and the older form may be deprecated in future.\n```kotlin\n    inputFile.set(file(\"path/to/your/schema/file/or/files\"))\n```\n\n### `pointer`\n\nThis is the earlier means of specifying a composite input file;\nthe [`inputs`](#inputs) section above is more flexible, and the older form may be deprecated in future.\n```kotlin\n    inputFile.set(file(\"path/to/your/file\")) // must be a single file, and the default is not allowed\n    pointer.set(\"/pointer/to/definitions\") // JSON Pointer to the object containing the definitions\n```\n\n### `include`\n\nThis is the earlier means of specifying classes to be included from a composite input file;\nthe [`inputs`](#inputs) section above is more flexible, and the older form may be deprecated in future.\n```kotlin\n    include.set(listof(\"IncludeThis\", \"AndThis\"))\n```\n\n### `exclude`\n\nThis is the earlier means of specifying classes to be included from a composite input file;\nthe [`inputs`](#inputs) section above is more flexible, and the older form may be deprecated in future.\n```kotlin\n    exclude.set(listof(\"NotThis\", \"NorThis\"))\n```\n\n### `outputDir`\n\nThe default output directory is `build/generated-sources/«language»`, where `«language»` is `kotlin`, `java` or\n`ts` (for TypeScript), depending on the target language.\nTo specify a different output directory, use:\n```kotlin\n    outputDir.set(file(\"path/to/your/output/directory\"))\n```\n\n### `language`\n\nThe default target language is Kotlin (naturally enough, for a project written in Kotlin and primarily intended to\ntarget Kotlin).\nTo specify Java output:\n```kotlin\n    language.set(file(\"java\"))\n```\nThe value of this setting must be `kotlin`, `java` or `typescript`.\n\nThis setting may be specified in the config file, and that is the recommended practice.\n\n### `packageName`\n\nBy default, classes will be generated without a `package` directive.\nTo supply a package name:\n```kotlin\n    packageName.set(file(\"com.example.model\"))\n```\n\nThis setting may be specified in the config file, and that is the recommended practice.\n\n### `generatorComment`\n\nThe `generatorComment` allows the provision of a line of text to be added to the comment block output to the start of\neach generated file:\n```kotlin\n    generatorComment.set(\"This was generated from Schema version 1.0\")\n```\n\nThis setting may be specified in the config file, and that is the recommended practice.\n\n### `classMappings`\n\nThis property allows the specification of custom types to be used for class properties or array items.\nIt has been superseded by the\n[`customClasses`](https://github.com/pwall567/json-kotlin-schema-codegen/blob/main/CONFIG.md#customclasses) facility of\nthe config file, and will probably be deprecated in future releases and eventually removed.\n\n### `schemaExtensions`\n\nThis property allows the specification of custom schema extensions to add validations to be mapped to certain\nkeyword-value combinations.\nIt has been superseded by the\n[`extensionValidations`](https://github.com/pwall567/json-kotlin-schema-codegen/blob/main/CONFIG.md#extensionvalidations)\nfacility of the config file, and will probably be deprecated in future releases and eventually removed.\n\n## Groovy\n\nMany people prefer to use the Groovy syntax for Gradle files, even for Kotlin-based projects.\nIn this case, the `buildscript` at the start of the `build.gradle` file will be:\n```groovy\nimport net.pwall.json.kotlin.codegen.gradle.JSONSchemaCodegenPlugin\n\nbuildscript {\n    repositories {\n        mavenLocal()\n    }\n    dependencies {\n        classpath(\"net.pwall.json:json-kotlin-gradle:0.119\")\n    }\n}\n```\nand the `apply` statement must be added **after** any `plugins` block:\n```groovy\napply plugin: JSONSchemaCodegenPlugin\n```\n\nTo compile the generated sources:\n```groovy\nsourceSets {\n    main.kotlin.srcDirs += \"build/generated-sources/kotlin\"\n}\n```\n\nThen, the configuration block (if required) will be something like:\n```groovy\njsonSchemaCodegen {\n    configFile = file('path/to/your/config.json')\n    inputFile = file('path/to/your/file/or/files')\n    pointer = '/pointer'\n    exclude = ['ExcludeThis', 'AndThis']\n    packageName = 'com.example.model'\n    generatorComment = 'This was generated from Schema version 1.0'\n}\n```\n(The `classMappings` and `schemaExtensions` sections are not available in Groovy.\nThe `inputs` section is also not available \u0026ndash; the `inputFile` and `pointer` definitions as shown in the above\nexample must be used instead.)\n\n## Gradle Warnings\n\nThis plugin has been tested with Gradle version 8.1.1.\nThe build process gives warnings about features that will be incompatible with future Gradle versions, but for the\nmoment it seems to be OK.\n\n(For Maven users, there is a Maven equivalent to this plugin \u0026ndash;\n[`json-kotlin-maven`](https://github.com/pwall567/json-kotlin-maven).)\n\nPeter Wall\n\n2025-04-13\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwall567%2Fjson-kotlin-gradle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpwall567%2Fjson-kotlin-gradle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwall567%2Fjson-kotlin-gradle/lists"}