7 ms·

Hey folks. Creator of Taxi here. Pretty chuffed to wake up and find Taxi on the front page of HN. We built Taxi originally as a "Better OpenAPI", being frust

Hey folks. Creator of Taxi here. Pretty chuffed to wake up and find Taxi on the front page of HN. We built Taxi originally as a "Better OpenAPI", being frustrated with the signal-to-noise ratio of OpenAPI / Swagger's format. However, over the years, we've found it shines when used to describe how data and APIs from different teams & systems can interoperate. Rather than describing an API endpoint as accepting a "String", it's much more descriptive to say "EmailAddress", or "WorkEmailAddress". By using these same scalar types to enrich models in other systems, you can start building pretty powerful knowledge graphs of how everything in your org hangs together. Happy to answer any questions.

rzazueta 4y ago
https://xkcd.com/927/ https://xkcd.com/927/ Edit: Sorry, that was probably not polite. But I've been here before too many times. IO Docs, RAML, Blueprint... I guess the question is - why should I adopt this if I'm already committed to the Open API ecosystem, and why should I consider it if I am still deciding?
- martypitt 4y ago
  We started trying to be a better OpenAPI, however the goals have shifted, and today we're trying to build a cross-team semantic language for describing data and APIs - one which describes how data and APIs from independent teams can interact. OpenAPI is a great way for someone to publish their API, so that another person can discover it, generate a Client SDK, and start building integrations. Taxi has the same goal, but for machines - so that software can automatically discover another API, and understand semantically how to interact with it. The two techs can co-exist quite happily, and you get great documentation benefits in embedding Taxi types in your OpenAPI spec [0] IMO, OpenAPI has a poor signal-to-noise ratio - a documentation tool you can't actually read without tooling. That feels misaligned to me. More importantly, OpenAPI doesn't do a good enough job in describing the semantics of a contract. What String should I pass to your API? EmailAddress or CustomerId? In this transaction, where do I place the BuyerCustomerId vs SellerCustomerId? That's an important distinction, which other tools aren't trying to address. With Taxi, we want to document APIs and Data in a way that tooling can understand across the organsiation, without having to fall back to reading docs, and that doesn't require shared models across the org. From there, we can build tooling can understand the semantics of an API, and then automate the integration (That's our other tool, Vyne). [0] https://docs.taxilang.org/generating-taxi-from-source/#examples https://docs.taxilang.org/generating-taxi-from-source/#examp...
  - meh2frdf 4y ago
    Unpopular opinion, but I think RDF and shacl solves a lot of this!
    - jcrites 4y ago
      I hadn't heard of RDF. I've tried to review its W3C material right now but the documentation is so abstract that I'm struggling to understand what idea it's trying to convey, or problem to solve. https://www.w3.org/TR/rdf11-concepts/ https://www.w3.org/TR/rdf11-concepts/ I think the concepts this document is trying to convey would be a lot clearer with an example of how one might use the concept to build a concrete system, and what problem the RDF technology helps solve. The overall description is "RDF is a standard model for data interchange on the Web." That seems to fall short from defining services and APIs, and then code generating client and/or server logic, which is the goal of Taxi and Smithy: https://awslabs.github.io/smithy/ https://awslabs.github.io/smithy/ RDF appears to be a data format, and I don't understand what benefit I'd get from using it, except perhaps that automated reasoning tools could potentially interact with my data more easily. But that is rarely a problem I have when building systems: maybe I'd consider this if I was in charge of building a government system that publishes official data to the public (and then also offer a CSV/JSON feed which everyone would probably use in practice), but when working in a private (corporate/organizational) environment, the benefits of RDF seem lackluster. The only immediate benefit I can think of would be that, using unique IRIs to represent business data types, I could perhaps see what systems across a company handle a particular type of data: but this would also be possible when using Smithy or Taxi (if appropriately reusing types and models across many interacting systems). The data format also appears to be reasonably verbose due to the inclusion of the field name and type for every field. But many of the systems I build are RPC and the client and service already have a shared model of the data that they will be exchanging. Including RDF's additional information would seem to result in a wire format that's lower performance than something built on a toolkit like Apache Thrift/gRPC/Capn'Proto, or even hand-coded HTTP APIs (as much as I despise that approach). What benefits would one get using RDF vs. defining an API using Taxi or Smithy, and then binding it to an efficient binary or text HTTP protocol representation? (E.g., BSON, FlatBuffers, etc.) If I wanted to serve self-describing data I'd be more inclined to use a technology like Ion, which is very concrete and simple to understand: https://amzn.github.io/ion-docs/ https://amzn.github.io/ion-docs/ The documents on SHACL are a bit clearer due to the inclusion of concrete examples, but I'm still not sure (1) what engineering problem I would face when building a system that these technologies would help me solve, and (2) is the actually usable (cross-platform) and robust, or is it largely a set conceptual ideas? There didn't seem to be many actively maintained open source projects focused on RDF. https://www.w3.org/TR/2017/REC-shacl-20170720/ https://www.w3.org/TR/2017/REC-shacl-20170720/ Please feel free to let me know if I'm underestimating or misunderstanding RDF. From my skim of its docs it seems like a data format, not a way to model APIs (and get down to business of giving them concrete protocols), which seems like a very crucial distinction from the problem that Taxi and Smithy solve. I suppose since RDF can describe "any" data, one could invent a set of data types that express operations, models, types, etc., but unless there's a standard set of types for expressing operations, models, types, and bindings to protocol interfaces, already, then you're leaving it to the developers of each service to define their own RDF representations of these things, which means that there wouldn't be similarity to modeling of these concepts across services, preventing universal automated reasoning or transformation. (Let me know if there's a spec for using RDF for defining service interfaces ... there are a lot of docs associated with that WG and I can't read them all before writing an HN comment :-) From all of what I've read, it looks like RDF is trying to define a data format that can be understood "universally" through the definition of well known IRIs; that feels like a different problem than defining a service interface, service stubs, and client libraries, that might be used privately within an organization for building client/server systems.
fjfaase 4y ago
Is there a distinction between values and references to values? Is there a concept of compound values and their components? Is there anything on referential constraints definition? Is it possible to indicate that an item cannot be removed if it is still used in another item? Or that if an item is removed other items that depend on it, should also be removed? See for some explaination about what I mean: https://github.com/FransFaase/DataLang https://github.com/FransFaase/DataLang

rzazueta 4y ago

https://xkcd.com/927/ https://xkcd.com/927/ Edit: Sorry, that was probably not polite. But I've been here before too many times. IO Docs, RAML, Blueprint... I guess the question is - why should I adopt this if I'm already committed to the Open API ecosystem, and why should I consider it if I am still deciding?

martypitt 4y ago
We started trying to be a better OpenAPI, however the goals have shifted, and today we're trying to build a cross-team semantic language for describing data and APIs - one which describes how data and APIs from independent teams can interact. OpenAPI is a great way for someone to publish their API, so that another person can discover it, generate a Client SDK, and start building integrations. Taxi has the same goal, but for machines - so that software can automatically discover another API, and understand semantically how to interact with it. The two techs can co-exist quite happily, and you get great documentation benefits in embedding Taxi types in your OpenAPI spec [0] IMO, OpenAPI has a poor signal-to-noise ratio - a documentation tool you can't actually read without tooling. That feels misaligned to me. More importantly, OpenAPI doesn't do a good enough job in describing the semantics of a contract. What String should I pass to your API? EmailAddress or CustomerId? In this transaction, where do I place the BuyerCustomerId vs SellerCustomerId? That's an important distinction, which other tools aren't trying to address. With Taxi, we want to document APIs and Data in a way that tooling can understand across the organsiation, without having to fall back to reading docs, and that doesn't require shared models across the org. From there, we can build tooling can understand the semantics of an API, and then automate the integration (That's our other tool, Vyne). [0] https://docs.taxilang.org/generating-taxi-from-source/#examples https://docs.taxilang.org/generating-taxi-from-source/#examp...
- meh2frdf 4y ago
  Unpopular opinion, but I think RDF and shacl solves a lot of this!
  - jcrites 4y ago
    I hadn't heard of RDF. I've tried to review its W3C material right now but the documentation is so abstract that I'm struggling to understand what idea it's trying to convey, or problem to solve. https://www.w3.org/TR/rdf11-concepts/ https://www.w3.org/TR/rdf11-concepts/ I think the concepts this document is trying to convey would be a lot clearer with an example of how one might use the concept to build a concrete system, and what problem the RDF technology helps solve. The overall description is "RDF is a standard model for data interchange on the Web." That seems to fall short from defining services and APIs, and then code generating client and/or server logic, which is the goal of Taxi and Smithy: https://awslabs.github.io/smithy/ https://awslabs.github.io/smithy/ RDF appears to be a data format, and I don't understand what benefit I'd get from using it, except perhaps that automated reasoning tools could potentially interact with my data more easily. But that is rarely a problem I have when building systems: maybe I'd consider this if I was in charge of building a government system that publishes official data to the public (and then also offer a CSV/JSON feed which everyone would probably use in practice), but when working in a private (corporate/organizational) environment, the benefits of RDF seem lackluster. The only immediate benefit I can think of would be that, using unique IRIs to represent business data types, I could perhaps see what systems across a company handle a particular type of data: but this would also be possible when using Smithy or Taxi (if appropriately reusing types and models across many interacting systems). The data format also appears to be reasonably verbose due to the inclusion of the field name and type for every field. But many of the systems I build are RPC and the client and service already have a shared model of the data that they will be exchanging. Including RDF's additional information would seem to result in a wire format that's lower performance than something built on a toolkit like Apache Thrift/gRPC/Capn'Proto, or even hand-coded HTTP APIs (as much as I despise that approach). What benefits would one get using RDF vs. defining an API using Taxi or Smithy, and then binding it to an efficient binary or text HTTP protocol representation? (E.g., BSON, FlatBuffers, etc.) If I wanted to serve self-describing data I'd be more inclined to use a technology like Ion, which is very concrete and simple to understand: https://amzn.github.io/ion-docs/ https://amzn.github.io/ion-docs/ The documents on SHACL are a bit clearer due to the inclusion of concrete examples, but I'm still not sure (1) what engineering problem I would face when building a system that these technologies would help me solve, and (2) is the actually usable (cross-platform) and robust, or is it largely a set conceptual ideas? There didn't seem to be many actively maintained open source projects focused on RDF. https://www.w3.org/TR/2017/REC-shacl-20170720/ https://www.w3.org/TR/2017/REC-shacl-20170720/ Please feel free to let me know if I'm underestimating or misunderstanding RDF. From my skim of its docs it seems like a data format, not a way to model APIs (and get down to business of giving them concrete protocols), which seems like a very crucial distinction from the problem that Taxi and Smithy solve. I suppose since RDF can describe "any" data, one could invent a set of data types that express operations, models, types, etc., but unless there's a standard set of types for expressing operations, models, types, and bindings to protocol interfaces, already, then you're leaving it to the developers of each service to define their own RDF representations of these things, which means that there wouldn't be similarity to modeling of these concepts across services, preventing universal automated reasoning or transformation. (Let me know if there's a spec for using RDF for defining service interfaces ... there are a lot of docs associated with that WG and I can't read them all before writing an HN comment :-) From all of what I've read, it looks like RDF is trying to define a data format that can be understood "universally" through the definition of well known IRIs; that feels like a different problem than defining a service interface, service stubs, and client libraries, that might be used privately within an organization for building client/server systems.

fjfaase 4y ago

Is there a distinction between values and references to values? Is there a concept of compound values and their components? Is there anything on referential constraints definition? Is it possible to indicate that an item cannot be removed if it is still used in another item? Or that if an item is removed other items that depend on it, should also be removed? See for some explaination about what I mean: https://github.com/FransFaase/DataLang https://github.com/FransFaase/DataLang