{"id":20114013,"url":"https://github.com/davidb/sandbox_cdevents_spec","last_synced_at":"2026-05-31T21:31:51.110Z","repository":{"id":261080602,"uuid":"883109118","full_name":"davidB/sandbox_cdevents_spec","owner":"davidB","description":"exploration of other way to define cdevents (and to generate doc, sdk,...)","archived":false,"fork":false,"pushed_at":"2025-03-04T17:47:53.000Z","size":101,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-17T06:22:16.300Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","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/davidB.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-11-04T11:49:28.000Z","updated_at":"2025-03-04T17:47:56.000Z","dependencies_parsed_at":"2024-11-04T16:20:17.201Z","dependency_job_id":"67ac8fd8-78f4-4fd5-bb3e-695adcfca1fd","html_url":"https://github.com/davidB/sandbox_cdevents_spec","commit_stats":null,"previous_names":["davidb/sandbox_cdevents_spec"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/davidB/sandbox_cdevents_spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidB%2Fsandbox_cdevents_spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidB%2Fsandbox_cdevents_spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidB%2Fsandbox_cdevents_spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidB%2Fsandbox_cdevents_spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidB","download_url":"https://codeload.github.com/davidB/sandbox_cdevents_spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidB%2Fsandbox_cdevents_spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33750474,"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-31T02:00:06.040Z","response_time":95,"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":[],"created_at":"2024-11-13T18:27:48.684Z","updated_at":"2026-05-31T21:31:51.092Z","avatar_url":"https://github.com/davidB.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sandbox_cdevents_spec\n\nExperiments with the [cdevents spec](https://github.com/cdevents/spec) to use an other format for specification of the events.\nAnd to generate documentation and SDK's models from the spec.\n\nTo have a relevent example, the experiment provide the 3 events (`{subject}.{predicate}`) (2 on the same subject):\n\n- `artifact.published`\n- `artifact.deleted` (to have 2 on the same subject)\n- `taskrun.started`\n- (optional) `testcaserun.started` (to have 2 on the same predicate)\n\n## Links\n\n- [cdevents spec](https://github.com/cdevents/spec)\n- [Friendly schema/spec for code generator (breaking change) · cdevents/spec · Discussion #240](https://github.com/cdevents/spec/discussions/240)\n- [Modeling language considerations for SDKs · Issue #5 · cdevents/implementation-wg](https://github.com/cdevents/implementation-wg/issues/5)\n\n## Features to Explore, to try\n\n- specification store on several files\n- code generation:\n  - polymorphism for subject/predicate\n  - typed scalars (aka \"string\" with format)\n    - date-time\n    - non-empty string\n    - purl\n    - uri-reference\n  - test, validation (runtime)\n  - description =\u003e api documentation\n  - example(s) =\u003e api documentation\n  - example(s) =\u003e tests (unit test or doctest)\n- doc: markdown\n  - description\n  - example(s)\n- possible customization of templates/generation\n- generate only models\n- generation of cli/server for conformance/contract test ?\n\n## Exploration's remarks\n\n### Json Schema\n\n- every spec ends with a `schema.json`\n- root as `cdevent.schema.json`\n- one file per type\n- use oneOf for polymorphism (but no discriminator as not supported by json schema)\n- use `const` for constant values (like `enum` with a single value)\n- try to use:\n  - [x] \u003chttps://quicktype.io/\u003e\n    - doesn't support json schema 2020-12 (try to switch to draft 07 \u0026 06)\n  - [ ] [schematools](https://github.com/kstasik/schema-tools)\n    - see also the OpenAPI section\n    - TODO try with \"discriminator\" (no in the spec, but could be managed by the tool)\n\n### OpenAPI\n\n- use [Taskfile](https://taskfile.dev/) to run actions (validate, codegen, docgen,...)\n- try to [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0.html#schema-object) (support in alpha/beta by most of the tools)\n  - In 3.0,\n    - models are extended on json schema draft-07\n  - In 3.1,\n    - models are extended on json schema 2020-12\n    - allow siblings info to $ref (like override of description)\n    - allow const? (part of json schema 2020-12)\n- use yaml format (less verbose than json, simpler for multi-line strings)\n- create a root `api.yaml` file without `path`, we focus on the `components` part (the models)\n- use of discriminator for subject/predicate\n- 2 approaches for the models:\n  - `v4m` try to match v0.4.0 of spec (see [comments in cdevent.yaml.disable](openapi/spec/v4m/cdevent.yaml.disable))\n  - `v6` more freedom on the model (see [comments in cdevent.yaml](openapi/spec/v6/cdevent.yaml))\n- OpenAPI ecosystem provide lot of codegenerator (see [OpenAPI.Tools - an Open Source list of great tools for OpenAPI.](https://openapi.tools/#sdk)), we will focus on few that allow to use our own templates (and maybe extensions)\n  - [x] [openapi-generator](https://openapi-generator.tech/)\n    - java based\n    - lot of templates, lot of contributors over time,\n    - documentations, examples \u0026 some articles (like [OpenAPI Custom Generator | Baeldung](https://www.baeldung.com/java-openapi-custom-generator))\n    - options to use templates but the template engine is logicless (logic =\u003e create a generator in java :-( )\n    - internal datamodel used by templates depend on the generator and should prepare/expose logic (isXxx)\n    - currently the one, I spent the most time on\n  - [x] ~~[swagger-codegen](https://github.com/swagger-api/swagger-codegen)~~\n    - openapi-generator is based on swagger-codegen, fork mainly due to ownership company vs community\n  - [ ] [schematools](https://github.com/kstasik/schema-tools)\n    - from rust ecosystem (not listed on OpenAPI.Tools)\n    - I like the approach (vs openapi-generator)\n    - early/ young project\n    - more powerful template engine (tera, based on jinja2, with more buitin functions than mustache or handlebars)\n    - buggy (not able to validate my spec but able to process it)\n    - I don't know how to use generate multiple files in some cases (eg. 1 file per type)\n    - The internal model used by template doesn't expose all the information (title, ...)\n    - Dereference looks a good idea but not to generate models, because it's not just an include and we lost title and additional info injected by our layout\n  - [ ] [Generator | AsyncAPI Initiative for event-driven APIs](https://www.asyncapi.com/tools/generator)\n    - javascript\n    - template packaged as npm package\n    - generate a full \"client\" (for messaging system)\n  - [ ] [Modelina | AsyncAPI Initiative for event-driven APIs](https://www.asyncapi.com/tools/modelina)\n    - javascript\n    - templating ?\n  - comparaison: [OpenAPI Generator vs Swagger Codegen v3: Which API Generator Is Best for Your Needs? - Engineer From Nepal](https://engineerfromnepal.com/blog/openapi-generator-vs-swagger-codegen-v3/), [FAQ: General | OpenAPI Generator](https://openapi-generator.tech/docs/faq/)\n\n### AsyncAPI\n\n[AsyncAPI](https://www.asyncapi.com/) is a specification for building asynchronous APIs.\n\n-\n- Difficult to debug generator (generic error message with no context eg: `X is not defined`)\n\n### Smithy\n\n[Smithy](https://smithy.io/2.0/index.html) is designed to create API for Resources oriented API (ala REST): resources definition and associated operations / lifecycles.\n\n- smithy is used by AWS to generate AWS SDKs\n- 2.0 is young and a lot of plugins(code generator) are \"work in progress\" (see [smithy-lang/awesome-smithy: Awesome Smithy is a curated list of awesome build-tools, code-generators, examples, and other resources related to the Smithy IDL.](https://github.com/smithy-lang/awesome-smithy#client-code-generators))\n  - repositories (plugins, ...) with a lot of contributors \u0026 activity (see \u003chttps://github.com/smithy-lang\u003e)\n  - plugins are coded in kotlin, java\n  - some plugins are \"intimidating\" (layout, number of files, \"complexity\", etc.)\n  - some plugins are not yet published on maven central (see \u003chttps://repo.maven.apache.org/maven2/software/amazon/smithy/\u003e) but already documented to be published (e.g. go, python, rust), in fact they are used locally to generate the AWS SDKs\n- useful traits (annotations) and way to define models\n- I didn't find how to only generate payload (data model) without all the service, operations, ... (except by extracting/copying the model from the generated code)\n- No \"clear\" control on the json representation of the model as it depends on the plugin \u0026 protocol\n\n### Conclusion \u0026 feelings (temporary)\n\n\u003e [!CAUTION]\n\u003e A breaking change with current spec, messages, SDK and existing ecosystem (could be a problem)\n\n- no ready to use generator (yet) with zero configuration for markdown, java, python, rust, go,...\n- generated code is only a part of the SDK or spec'documentation\n- generating samples from the spec will require a dedicated tool and template (like [Schemathesis](https://schemathesis.readthedocs.io/en/stable/) or [Specmatic](https://specmatic.io/)) based on examples or random data (like in property-based testing) based on one 1 SDK\n- having a single entrypoint in spec (json schema maybe extractred from the spec) will make validation of examples, or message simpler for non-SDK users\n- generator MUST support templates, extensions, and scalar (string) specialisation:\n  - predifined templates are minimal (enough to do the job)\n  - to keep the quality of current SDK\n  - to keep compatibility with existing \"primitive\" type (eg. no \"string\" for id, uri, etc.)\n  - to allow annotation of generated structures\n- support of multiple spec versions could become a problem (if SDK want it)\n- TODO? custom (homemade) generator with minimal logic in the \"generator\" and more logic in the \"template\" (ala schematools)\n- TODO? invest more time (contribution?) in some of the tools (openapi-generator, schematools, codegen, modelina)\n- TODO? change the spec to be more like in programming languages\n- TODO? review all events =\u003e normalize, remove duplication, add missing fields, etc.\n- TODO? complementary linter to validate rules over the spec (naming convention, use of $ref, etc.): pkl, cuelang, opa... ?\n- should SDK includes integration with CloudEvents, http frameworks, etc.?\n\n## Dev \u0026 Build\n\n- Use [mise (mise-en-place)](https://mise.jdx.dev/) to setup tools (java, task, ...)\n- Use [Taskfile](https://taskfile.dev/) to run actions (validate, codegen, docgen,...), installed by mise\n\n```sh\n❯ mise install\n❯ cd openapi\n❯ task --list\ntask: Available tasks for this project:\n* codegen:                     Generate code from the spec (all languages)\n* openapi-generator-cli:       allow to call openapi-generator-cli directly by passing arguments after `--` (eg. `task openapi-generator-cli -- help`)\n* schematools-cli:             allow to call schematools directly by passing arguments after `--` (eg. `task schematools-cli -- --help`)\n* validate:                    Validate the spec\n* codegen:go:                  Generate code from the spec (go)\n* codegen:java:                Generate code from the spec (java)\n* codegen:markdown:            Generate code from the spec (markdown) \u003c-- documentation\n* codegen:python:              Generate code from the spec (python)\n* codegen:rust:                Generate code from the spec (rust)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidb%2Fsandbox_cdevents_spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidb%2Fsandbox_cdevents_spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidb%2Fsandbox_cdevents_spec/lists"}