DEV Community: Marcos Placona

Understanding The Difference Between OpenAPI's 'oneOf', 'allOf', and 'anyOf'

Marcos Placona — Wed, 12 Mar 2025 14:53:00 +0000

Crafting precise and adaptable schemas is paramount in API design. OpenAPI offers several constructs to help define flexible and robust data models, the most powerful and flexible of which are oneOf, allOf, and anyOf. These keywords provide different ways to validate data against multiple schemas, making them essential for designing APIs that accommodate varied data structures while maintaining type safety.

Whether you’re designing your API using Laravel, Flask, Nest, Django, FastAPI, SpringBoot, Express, ASP.NET, or anything else. Understanding the key differences and how to use OpenAPI oneOf, allOf, and anyOf will help you design a more maintainable and future-proof API.

The Key Differences

oneOf – The data must validate against exactly one of the subschemas.
allOf – The data must validate against all the subschemas simultaneously.
anyOf – The data must validate against at least one (or more) of the subschemas.

Understanding these distinctions is crucial when designing OpenAPI definitions, as they directly impact SDK generation, data validation, and client-side type safety.

Understanding Subschemas

To understand these keywords, it’s first important to understand what a subschema is. At its simplest, a subschema is just a schema referenced in a larger, more complex schema. Take, for example, this basic schema that defines a Dog, Cat, and Animal. They are all schemas, but when Dog and Cat are referenced in Animal, they are subschemas of Animal.

This is similar to classes and subclasses, but the relationships are top-down rather than bottom-up. In this example, Dog does not inherit or extend from Animal and does not take on any of Animal’s attributes. Instead, Animal defines that Dog or Cat as possible subschemas that it can conform to.

components:
  schemas:
    Dog: # ...
    Cat: # ...
    Animal:
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Cat

OpenAPI `oneOf`: Ensuring Exclusive Schema Matching

Use OpenAPI oneOf when a value should conform to precisely one of the provided schemas. This is particularly useful when defining mutually exclusive options.

Example:

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
        petType:
          type: string
      discriminator:
        propertyName: petType
    Dog:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            bark:
              type: boolean
            dig:
              type: boolean
    Cat:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            meow:
              type: boolean
            scratch:
              type: boolean
    Animal:
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Cat'

Here, an Animal must be either a Dog or a Cat, but not both. This ensures that API consumers provide and receive well-structured data that conforms to differing expectations of Cat and Dog. For example, a user can provide a Dog that can bark and dig but cannot meow.

Pitfall: One common issue with oneOf is its strict validation. oneOf is exactly one. If none or more than one schema matches, validation will fail. While the “none case” is expected, the “more than one case” can confuse API consumers and developers.

OpenAPI `allOf`: Merging Multiple Schemas

Use OpenAPI allOf to create composite objects that inherit properties from multiple schemas. This is useful when reusing common schema elements while adding specific properties.

Example:

components:
  schemas:
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
    Person:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
    Employee:
      allOf:
        - $ref: '#/components/schemas/Person'
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            employeeId:
              type: string

Here, Employee is a combination of Person and Address, inheriting all their properties while adding employeeId. This is especially useful when generating SDKs, as the resulting type automatically includes all inherited fields. Any update to the definition of Person or Address will be automatically reflected in Employee.

Pitfall: Overusing allOf can create deeply nested structures that become difficult to manage and debug, especially when resolving conflicts between inherited properties.

OpenAPI `anyOf`: Flexible Validation Against Multiple Schemas

Use OpenAPI anyOf when a value should match at least one (but possibly more) of the subschemas. This is useful for handling partial matches.

Example:

components:
  schemas:
    Contact:
      anyOf:
        - type: object
          properties:
            email:
              type: string
              format: email
        - type: object
          properties:
            phone:
              type: string

Here, a Contact object must contain either an email, a phone, or both. This is useful for more flexible schemas where multiple data input formats are acceptable.

Pitfall: With anyOf, partial matches can lead to unintended behaviors if API consumers expect all properties always to be present. Defining required fields can mitigate this.

Recommended Practices

To effectively use OpenAPI’s oneOf, allOf, and anyOf, consider these best practices:

Document Clearly: Provide detailed documentation on how your API behaves to prevent confusion for API consumers.
Use Discriminators with oneOf: Implement a discriminator property to simplify schema resolution and avoid ambiguous validation errors.
Avoid Excessive Nesting with allOf: While allOf promotes schema reuse, excessive inheritance can lead to deeply nested structures that are difficult to maintain.
Define Required Fields for anyOf: If a schema under anyOf should always have a specific property, explicitly set it as required to avoid unexpected validation issues.
Test Thoroughly: Validate your OpenAPI specification using tools like liblab validate or Linters to catch misconfigurations early.

Implications for SDK Generation

Choosing between oneOf, allOf, and anyOf has a significant impact on how SDKs handle type definitions:

OpenAPI oneOf ensures that only one type is valid at a time, leading to strict type-checking.
OpenAPI allOf merges schemas, making SDKs generate fully composed types with inherited properties.
OpenAPI anyOf allows looser type enforcement, enabling SDKs to accept multiple valid structures.

Understanding these nuances helps design API contracts that are flexible and well-defined, ensuring a better developer experience and more reliable SDKs.

Conclusion

By effectively leveraging oneOf, allOf, and anyOf, API designers can create expressive and maintainable OpenAPI schemas, enhancing the developer experience across various integrations. Whether building SDKs or validating API responses, choosing the proper construct ensures your API remains robust and easy to consume.

This article was originally written by Jim Bennett for the liblab blog

This article was originally written for the liblab blog

Mastering OpenAPI Types: Best Practices for Data Types and Formats

Marcos Placona — Wed, 12 Mar 2025 10:51:50 +0000

The OpenAPI Specification is often associated with describing RESTful APIs, but don’t be fooled by the stereotype. Whether you’re designing a REST API or something that leans more toward RPC-based calls, OpenAPI’s data type system is robust enough to capture your API’s behavior precisely. In this post, we’ll dive into recommended practices for working with OpenAPI types and explore all the data types you can leverage, from strings and numbers to objects and arrays.

Why Precision Matters

Clarity is king when your API spec serves as both documentation and a blueprint for SDK generation. Overly loose definitions might be “valid” according to the spec, but they can cause headaches when tooling tries to generate SDKs, server stubs, or even API docs. Here’s what you should keep front-of-mind:

Be explicit. Define your types using the standardized formats.
Validate ruthlessly. Use attributes like required, readOnly, writeOnly, and validations (e.g., minItems, pattern) to avoid ambiguity.
Plan for tooling. Clear, explicit definitions make it easier for SDK generators and documentation tools to do their job without guesswork.

Let’s walk through each data type with best practices and real-world examples.

The OpenAPI Data Types

1. String

The string type is a workhorse of the OpenAPI spec. It can represent everything from simple text to complex data like encoded binary files. But to unlock its full potential, you must use formats and patterns wisely.

Formats

Official formats for strings include:

date: For RFC3339 dates (e.g., "2025-03-07").
date-time: For full timestamps (e.g., "2025-03-07T15:26:38Z").
password: A hint that the string holds sensitive data.
byte: Base64 encoded data.
binary: For raw binary data.

Outside the official list, you might see:

email
uuid
uri
hostname
ipv4/ipv6
full list here

Example:

schema:
  type: string
  format: date-time

Patterns

When you need to constrain string content further, add a regex pattern:

schema:
  type: string
  pattern: '^[a-zA-Z0-9_]+$'

Best practice: Always validate input where possible. A well-defined string improves API documentation and makes client-side parsing and generation predictable.

2. Number & Integer

Numbers are more than just digits on a screen. OpenAPI distinguishes between generic numbers and integers by allowing you to specify formats that align with your target language’s capabilities.

Formats for Numbers:

number
- float: For 32-bit floating point.
- double: For 64-bit floating point.
integer
- int32: 32-bit integer.
- int64: 64-bit integer.

Worth noting that JSON Schema defines integers mathematically, which means that both 1 and 1.0 are equivalent and considered integers.

Validation Attributes

Use attributes like minimum, maximum, exclusiveMinimum, exclusiveMaximum, and multipleOf to enforce numeric constraints.

Example for a 32-bit float:

schema:
  type: number
  format: float
  minimum: 0
  maximum: 1

Example for an integer with step constraints:

schema:
  type: integer
  format: int64
  multipleOf: 5

Tip: Explicitly specifying the format avoids any ambiguity that might arise from the default type handling in various languages.

3. Boolean

Simple but essential, the boolean type only accepts true or false. Unlike some loosely-typed systems, OpenAPI does not let you substitute 1 or 0.

Example:

schema:
  type: boolean

Best practice: Don’t try to be clever. Stick to true booleans to ensure consistent behavior across all consumers.

4. Array

Arrays let you define ordered lists of items. The key is to use the items attribute to specify the type of elements in the array.

Basic examples:

# Array of strings
schema:
  type: array
  items:
    type: string

# Array of objects with validations
schema:
  type: array
  items:
    type: object
    properties:
      id:
        type: integer
        format: int32
      name:
        type: string
  minItems: 1
  uniqueItems: true

Best practice: Utilize array-level validations (minItems, maxItems, uniqueItems) to enforce data integrity before it reaches your business logic.

5. Object

Objects in OpenAPI can be fully typed, serve as dictionaries, or be completely free-form. The level of detail you include can dramatically affect downstream processes like code generation.

Fully Typed Object

Define explicit properties with validations:

schema:
  type: object
  properties:
    username:
      type: string
    age:
      type: integer
      format: int32
    isActive:
      type: boolean
  required:
    - username
    - isActive

Dictionary (Using additionalProperties)

Use this for flexible key/value pairs where keys are always strings:

schema:
  type: object
  additionalProperties:
    type: string

Best practice: When possible, define all properties explicitly. Reserve free-form objects (additionalProperties: true or {}) for cases where the structure genuinely cannot be predetermined.

6. Null

OpenAPI 3.0 doesn’t have a separate null type. Instead, you mark a schema as nullable to indicate that it can be either a valid value or null.

Example:

schema:
  type: string
  nullable: true

Best practice: Overusing nullable can lead to ambiguity. Only mark a property as nullable if null is a valid, intentional state for that property.

Bringing It All Together

The beauty of OpenAPI lies in its versatility. While it’s renowned for RESTful API descriptions, its design supports the nuances of RPC-based calls and other HTTP paradigms. The secret to leveraging OpenAPI types effectively is to be explicit. By rigorously defining data types, formats, and validations, you enhance your API’s documentation and empower developers with tools that generate robust code and insightful documentation.

Remember, in the world of API design:

Clarity is non-negotiable.
Precision saves time down the line.
Explicit definitions lead to better tooling integration.

By following these practices, you’ll create OpenAPI specs that are as versatile and reliable as the APIs they describe.

Ready to take your API specifications to the next level? Explore more tips, best practices, and tools for creating bulletproof API documentation and client libraries at liblab.

Happy spec writing!

This article was originally written for the liblab blog

How to build an SDK from scratch: Tutorial & best practices

Marcos Placona — Fri, 04 Oct 2024 12:24:06 +0000

Life is too short to spend on writing boilerplate code, or dealing with the complexities of lowest common denominator tooling. I want to focus on the business problem I'm trying to solve, not the plumbing.

This is why I'm always a fan of a well-crafted SDK, a tool that makes it easy to use a service or API. In this post we look at the process of creating SDKs, from concept to creation, and show how you can automate the process using liblab.

What is an SDK?

Let's start with the basic question - what is an SDK? An SDK, short for Software Development Kit, is a set of tools written in one or more programming languages that make it easier to use a service or API. For this post, I will focus on SDKs for APIs, providing a wrapper around the direct REST calls that a user might make against an API.

An SDK is a great abstraction layer. It is written in the language the developer uses, and provides language idiomatic ways to call the API, managing all the hard stuff for you such as the HTTP calls, the mapping of JSON to objects, authentication, retries, and so on.

A good SDK drastically reduces the code you have to write.

The importance of an SDK

SDKs are important to improve the developer experience of using your service or API. They allow your users to focus on the business problem they are trying to solve, rather than the plumbing of calling your API. This is just as important for public facing APIs from SaaS companies, as it is for internal APIs used by your own developers from your corporate microservices.

Some benefits include:

Intellisense and code completion - you can see the methods and properties available to you, and the parameters they take in your IDE.
Authentication - the SDK can handle the authentication process for you, so you don't have to worry about it.
Built in best practices - you can embed best practices inside the SDK, such as retry logic, so that if a call fails due to rate limiting, the SDK will automatically retry the call after a short delay.

To learn more about the comparison between SDKs and calling APIs directly, check out our post SDK vs API, key distinctions.

How to Build an SDK

Creating SDKs is a multi-step process, and is very time consuming. Not only do you need to design and build the SDK, but you also will want to create SDKs in multiple languages to support your users needs.

This might be less important if you are building SDKs for internal APIs and you only use a single language - for example if you are a Java shop you may only need a Java SDK. However, if you are building a public facing API, you will want to support as many programming languages as possible, so that your users can use the language they are most comfortable with. You will probably want a TypeScript SDK or JavaScript SDK, a Python SDK, a C# SDK, a Java SDK, and so on depending on the programming language priorities of your users.

The steps you would take are:

Design your SDK
Build your SDK
Document your SDK
Test your SDK
Publish your SDK
Maintain your SDK

1. Design your SDK

The first step is to design the SDK. A typical pattern is to mimic the API surface, providing functions that act like your API endpoints. This is a great way to build an SDK - it means your documentation and other user guides can be essentially the same for your API and SDKs, with just different sample code to use the SDK rather than make an API call.

API specification

To do this you will need to know how your API works, which is why it is important that your API has documentation, ideally an API specification such as an OpenAPI spec. Some API designers will start from an OpenAPI spec, others will start with code and autogenerate the OpenAPI spec from that code. Either way, you need to have a good understanding of your API before you can start to design your SDK.

The act of designing your SDK can also be a great way to validate that you have a good, clean API design. If you find that your SDK is hard to design, or that you have to do a lot of work to make it easy to use, then this is a good sign that your API needs improvement. For some tips, check out our post on why your OpenAPI spec sucks.

Paths and components

OpenAPI specs have 2 sections that make designing your SDK easier - paths and components. The paths section defines the endpoints of your API, and the components section defines reusable components, such as schemas for request and response bodies, or security schemes.

You want to use components as much as possible to make it easier to understand the data that is being passed around. Using components also helps you to them as much as possible between endpoints.

For example, if you have an endpoint that returns a single user, it is cleaner to have that user defined as a components/schema/user object. You can then reference that in the endpoint that gets a single user, and wrap it as an array for an endpoint that gets multiple users.

From API spec to an SDK design

Once you have your API spec, you can start to design your SDK. A good design is to provide objects that wrap the requests and responses for your API endpoints, and methods that call the API endpoints.

You will need to consider:

What objects will encapsulate the components
How paths will be grouped and wrapped as methods
The interface to handle authentication
Each SDK language will have different idioms, libraries and best practices. You will need to decide how to handle these differences. This might be a challenge if you are not familiar with the language.
How to handle best practices such as retries. Do you implement this yourself, or use a library?
Naming conventions. It is important to create SDKs that use idiomatic code for the SDK language - for example, if you are building a Python SDK, you want to use Python idioms such as using snake_case for method names, and PascalCase for class names, whereas TypeScript would use camelCase for method names.

2. Build your SDK

After you have designed your SDK, you can start to build the code implementation. This is a manual process, and is very time consuming, especially if you have SDKs in multiple languages.

Components

First you want to create objects to wrap the requests and responses for your API endpoints, defined in the components/schemas section of your OpenAPI spec. These objects are often referred to as models or DTOs (data transformation objects). These are usually 'simple' objects that have properties that map to the properties on the schema, and allow you to write JSON mapping code (or use a built in library) to automatically map the JSON to the object.

Sometimes the objects can be more complex. For example if your API specification defines an anyOf or oneOf - an endpoint that can return one of a range of possible types. Some languages can support this through a union type, others cannot, so you will need to decide how to handle these types. Remember, you need to do this for every SDK language you want to support.

SDK methods

Once you have your models, you can start to build the SDK methods that call your API endpoints. These functions can take models as parameters, and return the models as responses.

You will need to handle making HTTP requests, and the mapping of JSON to objects. You will also need to handle the authentication process, and any other best practices you want to build in such as persisting the HTTP connection, retries and logging.

These methods might also need parameters to match the parameters for the endpoint - both path parameters and query parameters.

For example, if the endpoint is GET /llama/{id} with the Id as a path parameter, you might have a method like this:

class Llama(BaseService):
  def get_llama(self, id: int) -> Llama:

where the llama Id becomes a method parameter.

Grouping methods

A good practice is to group these functions into service classes. You might want to do it based off the endpoint - for example having the GET, POST, and PUT methods for a single endpoint in a single class.

API specifications can also define groupings of endpoints, such as OpenAPI tags, so you might want to group your functions based on these tags. You know your API, so pick a technique that works for you.

As you build these methods, you should abstract out as much logic as possible into base service classes, or helper methods. For example, you might want to abstract out the HTTP request logic, the JSON mapping logic, the authentication logic, and the retry logic. This way you can define it once, and share the logic with all your service methods.

SDK client

Finally you will want to put some kind of wrapper object, usually referred to as an SDK client, around the endpoints. This will be the single place to surface authentication, setting different URLs if you have a multi-tenant API, or support different API regions or environments. This is your users entry point to the SDK.

class Llamastore:
  def __init__(self, access_token="", environment=Environment.DEFAULT) -> None:
    # The llama service
    self.llama_service = LlamaService(access_token)

  # Set a different URL for different environments
  def set_base_url(self, url: str) -> None:

  # Set the API access token
  def set_access_token(self, token: str) -> None:

3. Document your SDK

An SDK is only as good as its SDK documentation. As you create SDKs, you will also need to write documentation that shows how to install, configure, and use the SDK. You will need to keep the documentation in sync with the SDK, and update it as the SDK evolves. This will then need to be published to a documentation web page, or included in the SDK package.

OpenAPI specs support inline documentation, from descriptions of paths and components, to examples of parameters and responses. This is a great way to document your API, and you can use this to generate proper documentation for your users.

4. Test your SDK

Once your SDK is built, you need to ensure that it works as expected. This means writing unit tests that verify:

The JSON expected by and returned by your API can map to the objects you have created
The HTTP requests are being made correctly by the SDK methods to the right endpoints
Authentication is implemented correctly
The best practices such as retries work as expected

You should write unit tests that mock the real endpoint, as well as integration tests that call a real endpoint in a sandbox or other test environment.

5. Publish your SDK

Your finished SDK needs to be in the hands of your users. This means publishing it to a package manager, such as npm for JavaScript, or PyPi for Python.

For every SDK language you will need to create the relevant package manifest, with links to your SDK documentation, and publish it to the package manager. For internal SDKs, you might want to publish it to a private package manager, such as GitHub packages, or a private npm registry.

6. Maintain your SDK

It's not enough to just create SDKs once. As your API evolves, you need to update your both your SDK and SDK documentation to reflect the changes. This is a manual process, and is very time consuming, especially if you have SDKs in multiple languages.

Your users will expect your SDK to be in sync with your API, ideally releasing new features to your SDK as soon as they are released to the API. As well as the engineering effort to update the SDK and SDK documentation, you also need to ensure that during SDK development, your internal processes track API updates, create tickets for the work to update the SDK, and ensure that the SDK is released at the same time as the API.

Every new endpoint would mean a new SDK method, or a new class depending on how you have structured your SDK. Every new schema is a new model class. Every change to an existing endpoint or schema is a change to the existing SDK method or model class. You may also need to update any best practices, such as supporting new authentication schemes, or adding new retry logic.

You will also need to track breaking changes, and update your SDK version as appropriate - a major version bump for breaking changes, a minor version bump for new features, and a patch version bump for bug fixes.

Best practices for building the perfect SDK

When building an SDK, there are a number of best practices you should follow to ensure that your SDK is easy to use, and works well for your users.

Provide good documentation and examples - your API spec should be full of well written descriptions, examples, and other documentation that can be ported to your SDK. This will make it easier for your users to get started quickly.
Use idiomatic code - your SDK should use the idioms of the language you are building the SDK for. It should match the language's naming conventions, use standard libraries, and follow the language's best practices. For example, using requests in Python, making all your C# methods async, using TypeScript's Promise for asynchronous methods, and so on.
Embed security best practices - take advantage of security best practices, from using the latest version of any dependencies with mechanisms to monitor for patches and provide updates, to using the latest security protocols and libraries.
Handle authentication - your SDK should handle authentication for your users. This might be as simple as providing a method to set an API key, or as complex as handling OAuth2. You should also provide a way to handle different environments, such as development, staging, and production.

Automating the SDK build with liblab

Creating SDKs is a lot of work that only gets bigger as your API grows, or you want to support more languages. This is where automation is your friend. liblab is a tool that can take your API specification, such as an OpenAPI spec, and autogenerate SDKs for you in multiple languages.

The SDK generation process will generate the models and service classes for you, with all the required mapping code. It will also generate your best practices such as authentication and retries, and you can configure these via a configuration file. You can also write code that is injected into the API lifecycle to add additional functionality, such as logging or custom authentication with the liblab hooks feature.

SDK generation is fast! A typical developer flow is to spend a few hours generating SDKs the first time as you configure the generation process to meet your needs. This is an iterative cycle of generate, check, adjust the configuration, then regenerate. Once you have your configuration the way you need, your SDKs are generated in seconds.

Adding more SDK languages is also fast - you add the new language to the configuration file, and regenerate.

liblab can also help you to keep your SDKs in sync with your API. As your API is updated, your SDK can be re-generated to match. For example, if your API spec lives in a git repository, you can set up a GitHub action to detect any changes, and regenerate your SDK, publishing the new SDK source code to your SDK repositories.

Finally liblab can generate your SDK documentation for you, with full code examples and all the documentation you need to get started. This is taken from your API specification, so is always in sync with your API.

Conclusion

SDKs are a powerful way to improve the developer experience of your API. They come with a cost - the amount of work needed to generate them. This is why automation is so important. With liblab you can automate the process of generating SDKs, and keep them in sync with your API as it evolves.

This article was originally written by Jim Bennett for the liblab blog

How to add Retrieval-Augmented Generation (RAG) to your app using generated SDKs

Marcos Placona — Thu, 03 Oct 2024 20:20:36 +0000

Everyone has heard of ChatGPT, the popular large language model (LLM) that can generate human like text, answering any question you may have with a certain degree of correctness. However, the biggest problem with these large language models is that they only have a limited amount of 'knowledge' to draw on - they are trained using data from the internet up to a particular date, and that is it.

For example, if you ask an LLM what todays date is, or what the weather is like in a particular city, it will not be able to answer you - it just doesn't have that data.

This lack of data also limits an LLMs ability to answer questions, or reason, based off your own data. For example, if you have a database of customer reviews, and you want to ask the LLM a question about the reviews, it will not be able to answer you as it simply doesn't have access to that data. This is where retrieval augmented generation (RAG) comes in, allowing you to retrieve data from your own systems to augment what the LLM can reason over.

What is RAG?

Retrieval augmented generation, or RAG, is the term for augmenting the data that goes into the LLM by retrieving data from other systems, and use that data to help the LLM generate answers to your questions.

RAG example

For example, if you have an app that will prompt an LLM to give you the average sentiment of a particular product, you can use RAG to augment the LLM with the customer reviews of that product by extracting the relevant data from your reviews database, then sending that data to the LLM to reason over.

How does your app implement RAG?

If you have a prompt-based app that allows the user to interact using pure text, then your app will start from a prompt that is user generated, such as "What is the average sentiment of the cuddly llama toy". Your app will then use some kind of LLM-powered app framework that has plugins - these are add-ons in the app that can retrieve data. This framework will use the LLM to determine which plugins it needs to call to get data, then send that data back to the LLM to reason over with an updated prompt.

How do you add RAG to your LLM app?

One of the best ways to build an LLM app is to use some kind of AI app framework, such as Semantic Kernel, or LangChain. These frameworks support multiple programming languages, and work with your LLM of choice, for example you can build an app in Python using LangChain that uses Llama 2, or an app in C# using Semantic Kernel that uses ChatGPT. These frameworks have a range of features built in that you would want for an LLM app, such as memory so that the results of one prompt can be used in the next.

These frameworks also support plugins - add-ons that you can build to extend the capability of the LLM, supporting tasks such as RAG. These plugins advertise their capabilities to the framework, and the LLM can use this information to decide which plugins to use depending on the prompt.

How do you build a plugin?

Plugins are built in the same language that you use to build your LLM app with the framework. For example, if you are building a C# app using Semantic Kernel, then you would build your plugin in C#. As part of defining your plugin, you provide a natural language description of what your plugin can do, and the framework will use this to decide which plugins to use.

Here's an example of the outline of a simple C# plugin for Semantic Kernel that retrieves cat facts:

public class CatFactPlugin
{
    [KernelFunction]
    [Description("Gets a cat fact.")]
    public async Task<string> GetCatFact()
    {
        // Do something here to get a cat fact
    }
}

Where does the data come from?

RAG is retrieval augmented generation, so the data that you use to augment the LLM has to be retrieved from somewhere. This could be a third party system, or ir could be one of your own internal systems. And typically you would access these systems via an API. So although we are in the shiny new world of AI, we are still back to the age old problem - we have to integrate with an API. And this means reading the API docs, worrying about authentication and retry strategies, building some JSON to make the request, and then parsing the JSON response, and all the issues that come with that.

How do SDKs help with RAG?

Let's be honest here - very few developers will interact directly with an API. We all write some kind of layer of abstraction over the API to make it easier to use. We write it, and we have to maintain it, which is a lot of work.

This is where generated SDKs come in. SDKs are software development kits that wrap the API, and provide a simpler way to interact with the API, the ultimate layer of abstraction. By using an SDK, you have strong typing (depending on your programming language of choice of course), best practices like authentication built in, and you don't have to worry about the JSON parsing. You also get autocomplete in your IDE, the ability for AI coding tools like GitHub copilot to help you, and inline documentation.

And the best thing about generated SDKs is that they are automatically generated from your OpenAPI spec. This means that you don't have to write the SDK, or maintain it - you just generate it, then use it. And once generated, it can be kept up to date automatically inside your CI/CD pipelines.

Generating SDKs for your RAG plugins

When it comes to generating SDKs, liblab is your friend. liblab is a platform that generates SDKs from your OpenAPI spec, so you can use them in your app. Whether you are accessing internal APIs, or third party APIs, all you need is an API spec, and liblab will generate the SDK for you.

We've recently released a full tutorial that will walk you through how to add retrieval augmented generation (RAG) to your AI app using autogenerated SDKs that wrap your internal APIs. This tutorial uses Semantic Kernel and ChatGPT, along with the C# SDK generation capabilities of liblab, and takes you through the process of building a plugin that retrieves cat facts, and using that plugin in your app. Whilst cat facts are important, I understand you probably want to use your own internal systems, but the same principals apply to any API!

Check it out on the liblab developer portal.

For example, to implement the cat fact plugin mentioned earlier, you could use the Cat Facts API. Using liblab, you can generate a C# SDK for the Cat Facts API.

You can find a liblab config file to generate the cat facts SDK in a template repo we've published to augment the tutorial.

Once you have the cat facts SDK, you can use it in your plugin to retrieve cat facts:

using CatFacts;

public class CatFactPlugin
{
    private readonly CatFactsClient _client = new();

    [KernelFunction]
    [Description("Gets a cat fact.")]
    public async Task<string> GetCatFact()
    {
        Console.WriteLine("CatFactPlugin > Getting a cat fact from the Cat Facts API...");
        var response = await _client.Facts.GetRandomFactAsync();
        Console.WriteLine("CatFactPlugin > Cat fact: " + response.Fact);
        return response.Fact;
    }
}

In this code, we just have 2 lines of code to get the cat facts from the SDK — the declaration of a field to hold the SDK client, and the call to the SDK to get the cat fact. The SDK takes care of all the complexity of calling the API, and parsing the response. Much nicer than writing all that code yourself!

This plugin can then be used in your app to retrieve cat facts, and augment the LLM with the data. For example, having the LLM give you the cat fact in the style of a pirate:

User > Give me a fact about cats in the style of a pirate
CatFactPlugin > Getting a cat fact from the Cat Facts API...
CatFactPlugin > Cat fact: A group of cats is called a clowder.
Assistant > Arr matey! Be ye knowin' that a gatherin' of meowin' seafarers,
them cats, be called a clowder? Aye, a fine group of whiskered buccaneers they be!

Again, maybe less helpful in the real world, but you get the idea! In the real world you could use the LLM to reason over your own data, for example retrieving data from an internal review system, and providing a list of the most popular products based off the reviews.

Conclusion

Adding retrieval augmented generation (RAG) to your AI app can be a powerful way to help your LLM reason over your own data. Using autogenerated SDKs to wrap your internal APIs makes it easier to add RAG to your app, giving you more time to focus on building the best AI experience for your users.

Get started with liblab today!

This article was originally written by Jim Bennett for the liblab blog

6 Practical tools for building a great engineering culture

Marcos Placona — Wed, 02 Oct 2024 13:13:35 +0000

At liblab, we tackle complex engineering problems to build SDKs for our customers and their end users, who are engineers themselves. Our team's extensive knowledge in software, software-as-a-service solutions, and developer tools is critical to our success. Therefore, retaining our talented developers is a priority.

Why should you care about engineering culture?

While it's often said that people leave managers, not jobs, it's equally true that engineers leave companies with poor culture. Engineering culture, shaped by the attitudes and experiences of software developers and team leaders, influences the working atmosphere. By understanding the importance of engineering culture, we can enhance the positive aspects and minimize the negative ones.

Practical tools for fostering a great engineering culture

There's a lot of discussion about building a great engineering culture on the internet. However, I'm focusing on practical tools here. These are concrete steps anyone can take to improve their team's culture and their own contributions.

1. Coding style and standards

Coding style is an aspect of engineering culture. It's not about specific preferences - we're not engaging in the tabs versus spaces debate! - but how coding style is shared across the team. Often, one "tastemaker" can influence the team's preferred style. If one engineer is the sole torchbearer, the implementation can seem arbitrary, and enforcing that style in code reviews with the wrong tone can alienate coworkers.

A coding standards document covers basic expectations like naming variables and functions, commit comments, and best practices. Creating these standards with feedback from the team fosters consensus and buy-in. Implementing a corresponding linting solution in the team’s IDEs and code repositories can clarify expectations and allow for early and regular corrections by the system, not a peer.

2. Developer tool choice

Another aspect of coding standards to consider is allowing tool choice. Not every developer likes the same IDE - some even prefer a traditional text editor! Allowing engineers to choose the solutions they’re most comfortable with will improve their satisfaction and productivity.

3. Code reviews and pair programming

Code reviews are routine tasks with a significant impact on culture. For engineers who don't pair on projects regularly, this could be their main professional interaction. Establishing a routine for code reviews ensures this important collaboration happens consistently. We recommend engineers spend time at the start of their day and after lunch on reviews to avoid a full-day wait for feedback. Alternatively, regular pair programming can reduce the need for code reviews since multiple engineers have evaluated the code already.

While experienced engineers analyze the code for style, functionality, and performance, every engineer can contribute. Less experienced engineers should be able to understand the code and changes. Asking for more information on a new function is a great reminder to include detailed comments! Seeing how others solve problems can spark new ideas and questions, leading to mentoring or collaboration. Participating in code reviews fosters relationships between developers, improving collaboration and culture.

4. Architecture discussions

Architecture discussions are some of my favorite times working in software engineering. Analyzing a problem, freely exchanging ideas, and incorporating elements into a cohesive solution represent the team's collective experience. Experienced engineers are naturally inclined to solve problems quickly, but these sessions are also opportunities to mentor and develop less experienced developers.

Encouraging experienced engineers to speak last allows the rest of the team to work through the problem together. Making a single engineer responsible for the project and the final decision on technical matters encourages strong ownership. This approach can also encourage participation from less experienced engineers, since they know an experienced engineer is ultimately responsible for the design.

5. Design reviews

Technical design reviews follow these architecture discussions. The responsible engineer details the proposed solution in a "request for comment" document, which the engineering team reviews asynchronously. If there are comments to consider, then a meeting is scheduled to discuss questions and collect feedback. This process gives every engineer a voice, promoting participation and an inclusive engineering culture.

6. Hiring

Hiring is another area where we can influence culture. New team members bring their own experiences and influence, but how we select them also matters. We at liblab prefer a take-home style coding challenge that closely reflects the daily developer experience. We've extensively discussed and iterated the content of this test, ending up with tests that target each of our engineering teams' focus areas.

Creating the test, having coworkers take it for a baseline, and evaluating the results is an important part of engineering culture. It establishes a minimum standard for the team, and completing the coding challenge becomes a shared experience and a badge of belonging for those who join.

Conclusion

Here are some practical tools for fostering a great engineering culture:

Promoting coding style through tools
Allow engineers to use their preferred tools
Setting ground rules for engineering discussions
Conducting inclusive design reviews
Regular code reviews and/or pair programming
Involving engineers in hiring practices
Anyone can adopt these practices within their own engineering team to enhance their culture. Teams should also experiment; what worked well for us at liblab might differ for your team.

If our commitment to a great culture sounds appealing, then come join us! We are hiring for a range of roles, and you can find more details at liblab.com/careers.

This article was originally written by Adrian Luff for the liblab blog

DEV Community: Marcos Placona

Understanding The Difference Between OpenAPI's 'oneOf', 'allOf', and 'anyOf'

The Key Differences

Understanding Subschemas

OpenAPI oneOf: Ensuring Exclusive Schema Matching

Example:

OpenAPI allOf: Merging Multiple Schemas

Example:

OpenAPI anyOf: Flexible Validation Against Multiple Schemas

Example:

Recommended Practices

Implications for SDK Generation

Conclusion

Mastering OpenAPI Types: Best Practices for Data Types and Formats

Why Precision Matters

The OpenAPI Data Types

1. String

Formats

Patterns

2. Number & Integer

Formats for Numbers:

Validation Attributes

3. Boolean

4. Array

5. Object

Fully Typed Object

Dictionary (Using additionalProperties)

6. Null

Bringing It All Together

How to build an SDK from scratch: Tutorial & best practices

What is an SDK?

The importance of an SDK

How to Build an SDK

1. Design your SDK

API specification

Paths and components

From API spec to an SDK design

2. Build your SDK

Components

SDK methods

Grouping methods

SDK client

3. Document your SDK

4. Test your SDK

5. Publish your SDK

6. Maintain your SDK

Best practices for building the perfect SDK

Automating the SDK build with liblab

Conclusion

How to add Retrieval-Augmented Generation (RAG) to your app using generated SDKs

What is RAG?

RAG example

How does your app implement RAG?

How do you add RAG to your LLM app?

How do you build a plugin?

Where does the data come from?

How do SDKs help with RAG?

Generating SDKs for your RAG plugins

Conclusion

6 Practical tools for building a great engineering culture

Why should you care about engineering culture?

Practical tools for fostering a great engineering culture

1. Coding style and standards

2. Developer tool choice

3. Code reviews and pair programming

4. Architecture discussions

5. Design reviews

6. Hiring

Conclusion

OpenAPI `oneOf`: Ensuring Exclusive Schema Matching

OpenAPI `allOf`: Merging Multiple Schemas

OpenAPI `anyOf`: Flexible Validation Against Multiple Schemas