/modelina

A library for generating data models based on inputs such as AsyncAPI, OpenAPI, or JSON Schema documents.

Primary LanguageTypeScriptApache License 2.0Apache-2.0

AsyncAPI Modelina blackbox pipeline status Coverage Status Project Status: Active – The project has reached a stable, usable state and is being actively developed. Maintenance score Npm latest version License last commit Discussions Website Playground All Contributors

Your one-stop tool for generating accurate and well-tested models for representing the message payloads. Use it as a tool in your development workflow, or a library in a larger integrations, entirely in your control.


Installing Modelina

Run this command to install Modelina in your project:

npm install @asyncapi/modelina

AsyncAPI CLI

If you have the AsyncAPI CLI installed (ONLY support AsyncAPI inputs), you can run the following command to use Modelina:

asyncapi generate models <language> ./asyncapi.json

What Does Modelina Do?

Modelina put YOU in control of your data models, here is how...

Modelina lets you generate data models from many types of inputs
const asyncapi = ...
const jsonschema = ...
const openapi = ... 
const metamodel = ... 
...
const models = await generator.generate(
  asyncapi | jsonschema | openapi | metamodel
);
Use the same inputs across a range of different generators
const generator = new TypeScriptGenerator();
const generator = new CsharpGenerator();
const generator = new JavaGenerator();
const generator = new RustGenerator();
...
const models = await generator.generate(input);
Easily let you interact with the generated models.
  • Want to show the generated models on a website? Sure!
  • Want to generate the models into files? Sure!
  • Want to combine all the models into one single file? Sure!

Whatever interaction you need, you can create.

const models = await generator.generate(input);
for (const model in models) { 
  const generatedCode = model.result;
  const dependencies = model.dependencies;
  const modeltype = model.type;
  const modelName = model.modelName;
  ...
}
Easily modify how models are constrained into the output
const generator = new TypeScriptGenerator({
  constraints: {
    modelName: ({modelName}) => {
      // Implement your own constraining logic
      return modelName;
    }
  }
});
Seamlessly layer additional or replacement code on top of each other to customize the models to your use-case
const generator = new TypeScriptGenerator({
  presets: [
    {
      class: {
        additionalContent({ content }) {
          return `${content}
public myCustomFunction(): string {
  return 'A custom function for each class';
}`;
        },
      }
    }
  ]
});
const models = await generator.generate(input);
Seamlessly lets you combine multiple layers of additional or replacement code
const myCustomFunction1 = {
  class: {
    additionalContent({ content }) {
      return `${content}
public myCustomFunction(): string {
return 'A custom function for each class';
}`;
    },
  }
};
const myCustomFunction2 = {...};
const generator = new TypeScriptGenerator({
  presets: [
    myCustomFunction1,
    myCustomFunction2
  ]
});
const models = await generator.generate(input);

Features

The following table provides a short summary of available features for supported output languages. To see the complete feature list for each language, please click the individual links for each language.

Supported inputs
AsyncAPI We support the following AsyncAPI versions: 2.0.0 -> 2.6.0, which generates models for all the defined message payloads. It supports the following schemaFormats AsyncAPI Schema object, JSON Schema draft 7, AVRO 1.9, RAML 1.0 data type, and OpenAPI 3.0 Schema.
JSON Schema We support the following JSON Schema versions: Draft-4, Draft-6 and Draft-7
OpenAPI We support the following OpenAPI versions: Swagger 2.0, OpenAPI 3.0 and 3.1, which generates models for all the defined request and response payloads.
TypeScript We currently support TypeScript types as file input for model generation
Meta model This is the internal representation of a model for Modelina, it is what inputs gets converted to, and what generators are provided to generate code. Instead of relying on an input processor, you can create your own models from scratch and still take advantage on the generators and the features.

Supported outputs
Java Class and enum generation: generation of equals, hashCode, toString, Jackson annotation, custom indentation type and size, etc
TypeScript Class, interface and enum generation: generation of example code, un/marshal functions, custom indentation type and size, etc
C# Class and enum generation: generation of example code, serializer and deserializer functions, custom indentation type and size, etc
Go Struct and enum generation: custom indentation type and size, etc
JavaScript Class generation: custom indentation type and size, etc
Dart Class and enum generation: json_annotation
Rust Struct/tuple and enum generation: generation of `implement Default`, generate serde macros, custom indentation type and size, etc
Python Class and enum generation: custom indentation type and size, etc
Kotlin Class and enum generation: use of data classes where appropriate, custom indentation type and size, etc
C++ Class and enum generation: custom indentation type and size, etc
PHP Class and enum generation: custom indentation type and size, descriptions, etc
Scala Class and enum generation: custom indentation type and size, descriptions, etc

Requirements

The following are a requirement in order to use Modelina.

Documentation

A feature in Modelina cannot exists without an example and documentation for it. You can find all the documentation here.

Examples

Do you need to know how to use the library in certain scenarios?

We have gathered all the examples in a separate folder and they can be found under the examples folder.

Versioning and maintenance

As of version 1, Modelina has a very strict set of changes we are allowed to do before it requires a major version change. In short, any changes that change the generated outcome are not allowed as it's a breaking change for the consumer of the generated models.

Here is a list of changes we are allowed to do that would not require a breaking change:

  • Adding new features (that do not change existing output), such as generators, presets, input processors, etc.
  • Change existing features, by providing options that default to current behavior. This could be a preset that adapts the output based on options, as long as the API of Modelina and the API of the generated models does not have any breaking changes.
  • Bug fixes where the generated code is otherwise unusable (syntax errors, etc).

Breaking changes are allowed and expected at a frequent rate, of course where it makes sense we will try to bundle multiple changes together.

We of course will do our best to uphold this, but mistakes can happen, and if you notice any breaking changes please let us know!

Because of the number of the limited number of champions, only the most recent major version will be maintained.

Major versions are currently happening at a 3-month cadence (in a similar fashion as the AsyncAPI specification), this will happen in January, April, June, and September.

Development

We try to make it as easy for you as possible to set up your development environment to contribute to Modelina. You can find the development documentation here.

Contributing

Without contributions, Modelina would not exist, it's a community project we build together to create the best possible building blocks, and we do this through champions.

We have made quite a comprehensive contribution guide to give you a lending hand in how different features and changes are introduced.

If no documentation helps you, here is how you can reach out to get help:

Contributors

Thanks go out to these wonderful people (emoji key):

Maciej UrbaΕ„czyk
Maciej UrbaΕ„czyk

πŸ› πŸ’» πŸ“– πŸ€” 🚧 πŸ’¬ ⚠️ πŸ‘€
czlowiek488
czlowiek488

πŸ› πŸ‘€ πŸ€”
Sergio Moya
Sergio Moya

πŸ› πŸ’» ⚠️ πŸ“– πŸ‘€
Jonas Lagoni
Jonas Lagoni

πŸ› πŸ’» πŸ“– πŸ€” 🚧 πŸ’¬ ⚠️ πŸ‘€
Lukasz Gornicki
Lukasz Gornicki

πŸ‘€ πŸ› πŸ’»
Arjun Garg
Arjun Garg

πŸ’»
Fran MΓ©ndez
Fran MΓ©ndez

πŸ‘€
Kanwal Singh
Kanwal Singh

πŸ’»
Alejandra Quetzalli
Alejandra Quetzalli

πŸ‘€ πŸ“–
MD SAIF  HUSAIN
MD SAIF HUSAIN

πŸ’‘ ⚠️ πŸ“– πŸ’»
Sudipto Ghosh
Sudipto Ghosh

πŸ’‘ ⚠️ πŸ“–
panwauu
panwauu

πŸ’» ⚠️ πŸ’‘ πŸ“– πŸ›
Stefan E. Mayer
Stefan E. Mayer

πŸ›
Talmiz Ahmed
Talmiz Ahmed

πŸ“– ⚠️ πŸ’‘
Marco
Marco

πŸ›
quadrrem
quadrrem

πŸ’» ⚠️
Kamil Janeček
Kamil Janeček

⚠️ πŸ› πŸ’»
mahakporwal02
mahakporwal02

πŸ’‘ ⚠️ πŸ“– πŸ’»
Debajyoti Halder
Debajyoti Halder

πŸ’» ⚠️ πŸ“– πŸ’‘ 🚧
Ritik Rawal
Ritik Rawal

πŸ“– πŸ’» ⚠️ πŸ’‘
Ishan
Ishan

πŸ’» ⚠️
Samriddhi
Samriddhi

πŸ’» ⚠️ πŸ“– πŸ’‘ 🚧
GΓ‘bor Magyar
GΓ‘bor Magyar

πŸ’» ⚠️ πŸ“– πŸ’‘
ibernabeudev
ibernabeudev

πŸ’» ⚠️ πŸ’‘ πŸ“–
Arkadiusz SΕ‚owikowski
Arkadiusz SΕ‚owikowski

πŸ’» ⚠️ πŸ’‘ πŸ“–
Willem Gillis
Willem Gillis

πŸ’» ⚠️ πŸ›
rmasarovic
rmasarovic

πŸ’» πŸ“– ⚠️ πŸ’‘
Owais Hasnath Ahmed
Owais Hasnath Ahmed

πŸ’» ⚠️ πŸ“–
PanMan
PanMan

πŸ“–
artur-ciocanu
artur-ciocanu

πŸ’» πŸ› πŸ’‘ πŸ“– ⚠️ 🚧
Cyprian Gracz
Cyprian Gracz

πŸ’» ⚠️ πŸ›
Leigh Johnson
Leigh Johnson

πŸ’» ⚠️ πŸ’‘ πŸ“– 🚧 πŸ‘€
Nitin Tejuja
Nitin Tejuja

⚠️ πŸ’‘
Kenneth Aasan
Kenneth Aasan

πŸ’» ⚠️ 🚧 πŸ“–
Amit Kumar Sharma
Amit Kumar Sharma

⚠️ πŸ“– πŸ’‘
Andrey Zaytsev
Andrey Zaytsev

πŸ’» πŸ’‘ πŸ“– ⚠️
Tenshi Codes
Tenshi Codes

πŸš‡
Yushi OMOTE
Yushi OMOTE

πŸ› πŸ’»
Zbigniew Malcherczyk
Zbigniew Malcherczyk

πŸ› πŸš‡ πŸ’» πŸ’‘ ⚠️ πŸ‘€
200Puls
200Puls

πŸ’» ⚠️
Anay Sarkar
Anay Sarkar

πŸ’‘ πŸ’» ⚠️
Louis Xhaferi
Louis Xhaferi

πŸ’»
Sambhav Gupta
Sambhav Gupta

πŸ“– πŸ‘€ 🎨 πŸ’» πŸ›
Abhay Garg
Abhay Garg

πŸ’» πŸ’‘ ⚠️ πŸ“–
henrikjon
henrikjon

πŸ’» ⚠️ πŸ“– πŸ’‘
Mohammad Yasir
Mohammad Yasir

πŸ’»
Savio Dias
Savio Dias

πŸ’» πŸš‡ πŸ›
Ishaan Shah
Ishaan Shah

πŸ’»
Shreyas0410
Shreyas0410

πŸ’»
beku-epitome
beku-epitome

πŸ’» πŸ‘€ ⚠️
Joshua Michael Daly
Joshua Michael Daly

πŸ›
Daniel KJ
Daniel KJ

πŸ’» ⚠️ πŸ’‘ πŸ‘€
Bhavik Agarwal
Bhavik Agarwal

🎨
Rishi
Rishi

πŸ’» 🎨
Rohith Boppey
Rohith Boppey

πŸ’» 🎨
Ashish Padhy
Ashish Padhy

πŸ’» ⚠️ πŸš‡
Jean-François Côté
Jean-François Côté

πŸ’» ⚠️ πŸ’‘ πŸ“–
Sumant.xD
Sumant.xD

⚠️ πŸš‡ πŸ’»
Aryan Singh
Aryan Singh

πŸ’»
Markus Poerschke
Markus Poerschke

πŸ’» ⚠️ πŸ’‘ πŸ“–
James Moey
James Moey

πŸ’» ⚠️
tomwolanski
tomwolanski

πŸ›
Kristupas
Kristupas

πŸ’»
Devansh-Bhatt
Devansh-Bhatt

⚠️ πŸš‡
Ansh Pancholi
Ansh Pancholi

πŸ’»
Maeght Loan
Maeght Loan

πŸ’» πŸ“–
Prince Rajpoot
Prince Rajpoot

πŸ’»
harshit mishra
harshit mishra

πŸ’»
PeteAudinate
PeteAudinate

πŸ’»
jano-petras
jano-petras

πŸ’» πŸ“– ⚠️
Nilkanth Parmar
Nilkanth Parmar

πŸ’» ⚠️ πŸ’‘ πŸ“–
Ashmit JaiSarita Gupta
Ashmit JaiSarita Gupta

πŸ’» 🎨 πŸ“– 🚧 ⚠️ πŸ‘€
Harshil Jani
Harshil Jani

πŸ’» ⚠️
Mintu Gogoi
Mintu Gogoi

⚠️
Devansh Mahant
Devansh Mahant

πŸ“–
Asish Kumar
Asish Kumar

πŸ“–
Ankur Singh
Ankur Singh

πŸ“–
RowlandBanks
RowlandBanks

πŸ’» ⚠️ πŸ›
Moritz Kalwa
Moritz Kalwa

πŸ’» ⚠️ πŸ› πŸ“–
Akshit Gupta
Akshit Gupta

πŸ’» πŸ›
Athul Tulasidasan
Athul Tulasidasan

πŸ’» πŸ’‘ πŸ“– ⚠️
souvik
souvik

πŸ’» ⚠️ πŸ’‘ πŸ“–
Louis-PhilippeGentile
Louis-PhilippeGentile

πŸ’» ⚠️ πŸ“– πŸ›

This project follows the all-contributors specification. Contributions of any kind are welcome!