{"id":29785856,"url":"https://github.com/cozystack/cozyvalues-gen","last_synced_at":"2026-05-27T20:32:36.145Z","repository":{"id":305217351,"uuid":"1022285152","full_name":"cozystack/cozyvalues-gen","owner":"cozystack","description":"OpenAPI schema and README generator for Helm","archived":false,"fork":false,"pushed_at":"2026-05-14T16:32:52.000Z","size":185,"stargazers_count":3,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T18:38:46.212Z","etag":null,"topics":["helm"],"latest_commit_sha":null,"homepage":"https://cozystack.io/","language":"Go","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/cozystack.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-18T19:20:44.000Z","updated_at":"2026-03-25T10:39:48.000Z","dependencies_parsed_at":"2025-08-07T23:16:05.142Z","dependency_job_id":"53aab967-8d6f-4eda-83b0-50dadfa7b0f4","html_url":"https://github.com/cozystack/cozyvalues-gen","commit_stats":null,"previous_names":["cozystack/cozyvalues-gen"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/cozystack/cozyvalues-gen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cozystack%2Fcozyvalues-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cozystack%2Fcozyvalues-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cozystack%2Fcozyvalues-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cozystack%2Fcozyvalues-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cozystack","download_url":"https://codeload.github.com/cozystack/cozyvalues-gen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cozystack%2Fcozyvalues-gen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33583394,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"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":["helm"],"created_at":"2025-07-27T17:35:50.915Z","updated_at":"2026-05-27T20:32:36.139Z","avatar_url":"https://github.com/cozystack.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cozyvalues-gen\n\nTiny helper that turns **JSDoc-annotated `values.yaml`** files into:\n\n1. **Go structs** – strongly typed, IDE-friendly.\n2. **CustomResourceDefinitions (CRD)** – produced by `controller-gen`.\n3. **values.schema.json** – OpenAPI schema extracted from the CRD.\n4. **README.md** – auto-updated `## Parameters` section.\n\nThe chain \"_structs → CRD → OpenAPI_\" re-uses the same code that Kubernetes itself relies on, so you get **maximum type compatibility** for free.\n\n## Syntax Overview\n\nUses **JSDoc-like syntax** for clean, readable type annotations:\n\n---\n\n## How it works\n\n```mermaid\ngraph LR\n    A[values.yaml] --\u003e B(Go structs)\n    B --\u003e C[CRD YAML]\n    C --\u003e D[values.schema.json]\n    A --\u003e E[README.md]\n```\n\n- Annotate your `values.yaml` (see [examples](examples) for the exact syntax).\n- Run cozyvalues-gen; it parses the comments and spits out Go code.\n- controller-gen compiles that code, emitting a CRD.\n- The tool trims the CRD down to a Helm-compatible schema.\n\n### Usage (one-liner)\n\n```\ncozyvalues-gen \\\n  --values values.yaml \\\n  --schema values.schema.json\n```\n\nSee `cozyvalues-gen` -h for all flags.\n\n## Installation\n\n### Homebrew (macOS and Linux)\n\n```bash\nbrew tap cozystack/tap\nbrew install cozyvalues-gen\n```\n\n\u003e **Note**: This uses our [incubating tap](https://github.com/cozystack/homebrew-tap). The formula will be submitted to official homebrew/core once it reaches 75+ stars and stable adoption.\n\n### Using `go install`\n\nRequires Go toolchain installed and accessible via `$PATH`.\n\n```console\ngo install github.com/cozystack/cozyvalues-gen@latest\n```\n\nThe binary lands in `$(go env GOPATH)/bin` (usually `~/go/bin`). Make sure that directory is on your `$PATH`.\n\n### Download a pre‑built release binary\n\nHead over to [https://github.com/cozystack/cozyvalues-gen/releases](https://github.com/cozystack/cozyvalues-gen/releases), grab the archive for your OS/arch, unpack it somewhere on your `$PATH`.\n\n## Annotation Tags\n\n### @param\nDefines a top-level parameter:\n```yaml\n## @param {type} name - description\n## @param {string} hostname - Server hostname\nhostname: \"example.com\"\n\n## @param {int} replicas - Number of replicas\nreplicas: 3\n```\n\n### @typedef\nDefines a custom type (struct):\n```yaml\n## @typedef {struct} Database - Database configuration\n## @field {string} host - Database host\n## @field {int} port - Database port\n\n## @param {Database} database - Database config\ndatabase:\n  host: localhost\n  port: 5432\n```\n\n### @field / @property\nDefines fields within a typedef (@property is a synonym):\n```yaml\n## @typedef {struct} User\n## @field {string} name - User name\n## @field {string} [email] - Email (optional, with omitempty)\n## @field {int} age=18 - Age with default value\n```\n\n### @enum\nDefines an enumeration type:\n```yaml\n## @enum {string} Size - Size preset\n## @value small\n## @value medium\n## @value large\n\n## @param {Size} size=\"medium\" - Selected size\nsize: \"medium\"\n```\n\n### Special Syntax\n\n- **Optional fields**: `[fieldName]` adds `omitempty` to JSON tag\n- **Pointers**: `{*type}` or `{?type}` (equivalent)\n- **Default values**: `fieldName=value` or `fieldName=\"value\"`\n\n### Validation constraints\n\nStack these tags on the line(s) after a `@param` or `@field`. They emit kubebuilder validation markers on the generated Go struct and JSON-schema entries in `values.schema.json`.\n\n```yaml\n## @param {int} port - Port number\n## @minimum 1\n## @maximum 65535\nport: 8080\n\n## @param {string} name - DNS-compatible name\n## @minLength 1\n## @maxLength 63\n## @pattern ^[a-z0-9-]+$\nname: \"\"\n\n## @param {[]string} tags - Tag list\n## @minItems 1\n## @maxItems 10\ntags: []\n\n## @param {string} storageClass - StorageClass used to store the data.\n## @immutable\nstorageClass: \"\"\n```\n\nAvailable constraints: `@minimum`, `@maximum`, `@exclusiveMinimum`, `@exclusiveMaximum`, `@minLength`, `@maxLength`, `@pattern`, `@minItems`, `@maxItems`, `@immutable`.\n\n**Placement matters.** Every constraint attaches to the most-recent `@param` or `@field` declaration. Place constraints **immediately after** the `@param`/`@field` header and **before** the YAML value line. If a constraint appears after the YAML value (e.g. floating between two `@param` blocks), it still attaches to the preceding `@param` for backwards compatibility, but `cozyvalues-gen` prints\n\n```\ncozyvalues-gen: \u003cfile\u003e:\u003cline\u003e: warning: constraint on this line still attaches to \"\u003cfield\u003e\" across an intervening YAML value line; move it to immediately after the @param/@field header for clarity\n```\n\nso the misplacement is visible in `make generate` output. The warning never fails the build — fix the placement to silence it.\n\n`@immutable` is a flag (no argument). It emits a CEL `XValidation` rule (`self == oldSelf`) at the property level. **Caveat**: per Kubernetes `x-kubernetes-validations` semantics, a property-level rule is evaluated only when the property is present in both `oldSelf` and `self`. For optional/omitempty/pointer fields the rule therefore enforces *immutable once set* rather than *immutable from creation* — the field can still be added on a subsequent update if it was absent on create. To enforce *immutable from creation* make the field required (omit `[name]` brackets and pointer markers).\n\n## Supported value types\n\n| Annotation token               | Go type                                    | JSON Schema             | Examples                             |\n| ------------------------------ | ------------------------------------------ | ----------------------- | ------------------------------------ |\n| `string`                       | `string`                                   | string                  | `\"hello\"`                            |\n| `bool`                         | `bool`                                     | boolean                 | `true`                               |\n| `int`, `int32`, `int64`        | matching signed integer                    | number                  | `42`                                 |\n| `float32`, `float64`           | matching float                             | number                  | `3.14`                               |\n| `quantity`                     | `resource.Quantity`                        | string                  | `\"500Mi\"`, `\"100m\"`, `\"4Gi\"`         |\n| `duration`                     | `metav1.Duration`                          | string                  | `\"5m\"`, `\"1h30m\"`                    |\n| `time`                         | `metav1.Time`                              | string (RFC 3339)       | `\"2025-08-07T12:00:00Z\"`             |\n| `object`                       | `k8sRuntime.RawExtension`                  | any JSON/YAML           | `{\"aaa\": 123, \"foo\": \"bar\"}`         |\n| `emptyobject`                  | empty struct (`struct{}`) **–** no fields  | `{}`                    | `{}`                                 |\n| `intOrString`                  | `intstr.IntOrString`                       | `anyOf` int or string   | `100`, `\"100\"` (PostgreSQL params)   |\n| `*\u003cprimitive\u003e`                 | pointer to that primitive (`nil` allowed)  | primitive or `null`     | `\"asd\"`, `null` …                    |\n| `\u003cCustomType\u003e`                 | generated struct                           | object                  | declared from `@field` annotations   |\n| `*\u003cCustomType\u003e`                | pointer to generated struct                | object or `null`        | `null`                               |\n| `[]\u003cT\u003e`                        | slice / YAML sequence                      | list                    | `[]string`, `[]*int`, `[]CustomType` |\n| `map[string]\u003cT\u003e`               | map / YAML mapping                         | object                  | keys are always **strings**          |\n\n### String-format aliases\n\nThese tokens map to a plain `string` field, **plus** `format: \"\u003calias\u003e\"` in the OpenAPI schema:\n\n| `format`        | Example value                          |\n| --------------- | -------------------------------------- |\n| `bsonobjectid`  | `507f1f77bcf86cd799439011`             |\n| `uri`           | `https://grafana.example.com`          |\n| `email`         | `user@example.com`                     |\n| `hostname`      | `db.internal`                          |\n| `ipv4`          | `192.168.0.10`                         |\n| `ipv6`          | `2001:db8::1`                          |\n| `cidr`          | `10.0.0.0/24`                          |\n| `mac`           | `00:1A:2B:3C:4D:5E`                    |\n| `uuid`, `uuid3`, `uuid4`, `uuid5` | `550e8400-e29b-41d4-a716-446655440000` |\n| `isbn`, `isbn10`, `isbn13`        | `9783161484100`      |\n| `creditcard`    | `4242 4242 4242 4242`                  |\n| `ssn`           | `123-45-6789`                          |\n| `hexcolor`      | `#ff8800`                              |\n| `rgbcolor`      | `rgb(255,136,0)`                       |\n| `byte`          | `SGVsbG8=` (base64)                    |\n| `password`      | *(hidden by most UIs)*                 |\n| `date`          | `2025-08-07`                           |\n\n\u003e **Tip:** use any alias exactly like a regular type, e.g.  \n\u003e ```yaml\n\u003e ## @param apiURL {uri} External URL of the API\n\u003e apiURL: \"\"\n\u003e ```\n\n---\n\nCreated for the Cozystack project. 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcozystack%2Fcozyvalues-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcozystack%2Fcozyvalues-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcozystack%2Fcozyvalues-gen/lists"}