4 ms·

What's the benefit over existing variants like Swagger/OpenAPI/JsonSchema ?

by whizzter 2y ago

mariocesar 2y ago
It feels like a convert solution, as it can transform TypeSchema into JsonSchema.
RedShift1 2y ago
Heh feels like Json schema to me too... Same, but different.
- drdaeman 2y ago
  Feels much weaker/naive than JSON Schema, as TypeSchema barely has any constraints. The TypeSchema spec is hard to comprehend as it doesn't delve into any details and looks like just a bunch of random examples with comments than a proper definitive document (e.g. they don't ever seem to define what "date-time" string format is). I don't see a way to say, e.g., that a string must be an UUIDv7, or that an integer must be non-negative, or support for heterogeneous collections, etc etc. Maybe it has some uses for code generation across multiple languages for very simple JSON structures, but that feels like a very niche use case. And even then, if you have to hook up per-language validation logic anyway (and probably language-specific patterns too, to express concepts idiomatically), what's the point of a code generator?
  - amanzi 2y ago
    "What is the difference to JSON Schema? JSON Schema is a constraint system which is designed to validate JSON data. Such a constraint system is not great for code generation, with TypeSchema our focus is to model data to be able to generate high quality code." They have more details on the History page.
    - drdaeman 2y ago
      Yeah, I've edited my comment above and added the last paragraph with a note about it. Must be a really weird use case when you need to write a bunch of code in different languages (probably writing libraries for some API or JSON-based data interchange format?), and is also not concerned about validation and language - because if you need validation, you're writing code by hand either way, so code generation becomes a curse rather than a blessing. I would've understood if it would do the inverse - read source code in any of the supported languages, and check if the structures it define it conforms to the schema. That would make sense for testing that those structs aren't too diverging between codebases (have the same-shaped fields). Even then I'm not sure I see the point because various languages tend to use different language-specific things (like an UUID type or enums/symbols/atoms, etc.) to make developer feel at home rather than in a barren JSONland.
    - dragonwriter 2y ago
      Those are certainly words, but since the words they use to describe what differentiates them form JSON Schema is just asserting that their thing is for exactly what has always motivated schema languages including, but not limited to, JSON Schema, and since JSON Schema supports that purpose far better, I am left confused At best, I can guess that maybe they are trying to get at the fact that JSON schema supports some structures that can be awkward or unidiomatic for data models in some languages (a lot of what you can do via allOf or oneOf fits this) and they want to narrow down to something where what can be defined in the schema language is also simple idiomatic structures nearly everywhere, but a restricted profile of JSON Schema would get you there much faster than starting from the ground up.
      - drdaeman 2y ago
        > narrow down to something where what can be defined in the schema language is also simple idiomatic structures nearly everywhere It feels more like a lowest common denominator to me, which is frequently (in presence of anything non-trivial) the opposite of idiomatic. For example, JSON does not have monetary/decimal type, best option available is a string. It would be very opposite of idiomatic to have a C# or Python code use a string in the record/dataclass, instead of a decimal, if the actual JSON document field has the "monetary value" semantic. And TypeSchema seem to ignore aspects like nullability and presence requirements, making assumptions that everything can be null (which can be wrong and even harmful, as if Java haven't taught us anything). Maybe I'm thinking wrong about it and the idea is to have separate wire and public API formats, though, where the wire format is minimal JSON (TypeSchema can work, I guess, although I still have concerns about nulls - and distinguishing between nulls and absence of the field) and then that intermediate almost-over-the-wire-but-deserialized-from-JSON-blob object representation is adapted into a language-specific idiomatic structure. I always felt that such approach is way too verbose and adds a lot of boilerplate without a good reason, but I could be wrong about it.
        dragonwriter 2y ago
        Yeah, “idiomatic” may have been a poor word choice, I really meant closer to “simply representable”. oneOf, for instance, lets you very easily define flexible, concise structures in JSON Schema that OO languages without union types may not express naturally if at all, and which may not be natural to work with even if they cna be expressed in many languages.
8338550bff96 2y ago
Yeah, I'm not really following the line of reasoning presented on the "/history" page: https://typeschema.org/history https://typeschema.org/history It seems to me like a mischaracterization of JSON Schema to say you can't define a concrete type without actual data. I am a very stupid individual so I could be misunderstanding the argument.
- dangsux 2y ago
  [dead]
- andix 2y ago
  I can't really follow those arguments either. For example the empty object example {}. Why is this bad? Types without properties are a real thing. Also an empty schema is a real thing. The thought I do get: JSON Schema primarily describes one main document (object/thing). And additionally defines named types (#/definitions/Student). But it's totally fine to just use the definitions for code generation. The reference semantics of JSON Schema is quite powerful, a little bit like XML with XSD and all the different imports and addons.
  - llamaLord 2y ago
    Maybe it's just me, but I've never been able to get a complex type schema to work properly with JSON schema. The moment you have types referencing other types in a way that can become recursive in ANY way, the whole thing seems to explode.
mchicken 2y ago
It looks far more constrained, especially when it comes to the validation logic, which makes sense validation-wise but honestly quickly becomes a "fate shovels shit in my face" kind of situation when it comes to code generation. As much as I love this sort of constraints I also find the union-type discrimination style "meh".

What's the benefit over existing variants like Swagger/OpenAPI/JsonSchema ?

mariocesar 2y ago

It feels like a convert solution, as it can transform TypeSchema into JsonSchema.

RedShift1 2y ago

Heh feels like Json schema to me too... Same, but different.

drdaeman 2y ago
Feels much weaker/naive than JSON Schema, as TypeSchema barely has any constraints. The TypeSchema spec is hard to comprehend as it doesn't delve into any details and looks like just a bunch of random examples with comments than a proper definitive document (e.g. they don't ever seem to define what "date-time" string format is). I don't see a way to say, e.g., that a string must be an UUIDv7, or that an integer must be non-negative, or support for heterogeneous collections, etc etc. Maybe it has some uses for code generation across multiple languages for very simple JSON structures, but that feels like a very niche use case. And even then, if you have to hook up per-language validation logic anyway (and probably language-specific patterns too, to express concepts idiomatically), what's the point of a code generator?
- amanzi 2y ago
  "What is the difference to JSON Schema? JSON Schema is a constraint system which is designed to validate JSON data. Such a constraint system is not great for code generation, with TypeSchema our focus is to model data to be able to generate high quality code." They have more details on the History page.
  - drdaeman 2y ago
    Yeah, I've edited my comment above and added the last paragraph with a note about it. Must be a really weird use case when you need to write a bunch of code in different languages (probably writing libraries for some API or JSON-based data interchange format?), and is also not concerned about validation and language - because if you need validation, you're writing code by hand either way, so code generation becomes a curse rather than a blessing. I would've understood if it would do the inverse - read source code in any of the supported languages, and check if the structures it define it conforms to the schema. That would make sense for testing that those structs aren't too diverging between codebases (have the same-shaped fields). Even then I'm not sure I see the point because various languages tend to use different language-specific things (like an UUID type or enums/symbols/atoms, etc.) to make developer feel at home rather than in a barren JSONland.
  - dragonwriter 2y ago
    Those are certainly words, but since the words they use to describe what differentiates them form JSON Schema is just asserting that their thing is for exactly what has always motivated schema languages including, but not limited to, JSON Schema, and since JSON Schema supports that purpose far better, I am left confused At best, I can guess that maybe they are trying to get at the fact that JSON schema supports some structures that can be awkward or unidiomatic for data models in some languages (a lot of what you can do via allOf or oneOf fits this) and they want to narrow down to something where what can be defined in the schema language is also simple idiomatic structures nearly everywhere, but a restricted profile of JSON Schema would get you there much faster than starting from the ground up.
    - drdaeman 2y ago
      > narrow down to something where what can be defined in the schema language is also simple idiomatic structures nearly everywhere It feels more like a lowest common denominator to me, which is frequently (in presence of anything non-trivial) the opposite of idiomatic. For example, JSON does not have monetary/decimal type, best option available is a string. It would be very opposite of idiomatic to have a C# or Python code use a string in the record/dataclass, instead of a decimal, if the actual JSON document field has the "monetary value" semantic. And TypeSchema seem to ignore aspects like nullability and presence requirements, making assumptions that everything can be null (which can be wrong and even harmful, as if Java haven't taught us anything). Maybe I'm thinking wrong about it and the idea is to have separate wire and public API formats, though, where the wire format is minimal JSON (TypeSchema can work, I guess, although I still have concerns about nulls - and distinguishing between nulls and absence of the field) and then that intermediate almost-over-the-wire-but-deserialized-from-JSON-blob object representation is adapted into a language-specific idiomatic structure. I always felt that such approach is way too verbose and adds a lot of boilerplate without a good reason, but I could be wrong about it.
      - dragonwriter 2y ago
        Yeah, “idiomatic” may have been a poor word choice, I really meant closer to “simply representable”. oneOf, for instance, lets you very easily define flexible, concise structures in JSON Schema that OO languages without union types may not express naturally if at all, and which may not be natural to work with even if they cna be expressed in many languages.

8338550bff96 2y ago

Yeah, I'm not really following the line of reasoning presented on the "/history" page: https://typeschema.org/history https://typeschema.org/history It seems to me like a mischaracterization of JSON Schema to say you can't define a concrete type without actual data. I am a very stupid individual so I could be misunderstanding the argument.

dangsux 2y ago
[dead]
andix 2y ago
I can't really follow those arguments either. For example the empty object example {}. Why is this bad? Types without properties are a real thing. Also an empty schema is a real thing. The thought I do get: JSON Schema primarily describes one main document (object/thing). And additionally defines named types (#/definitions/Student). But it's totally fine to just use the definitions for code generation. The reference semantics of JSON Schema is quite powerful, a little bit like XML with XSD and all the different imports and addons.
- llamaLord 2y ago
  Maybe it's just me, but I've never been able to get a complex type schema to work properly with JSON schema. The moment you have types referencing other types in a way that can become recursive in ANY way, the whole thing seems to explode.

mchicken 2y ago

It looks far more constrained, especially when it comes to the validation logic, which makes sense validation-wise but honestly quickly becomes a "fate shovels shit in my face" kind of situation when it comes to code generation. As much as I love this sort of constraints I also find the union-type discrimination style "meh".