A Discussion on: A1-PMS Compliance with O-RAN Specifications

WORK IN PROGRESS

Introduction: A1-PMS Compliance with O-RAN Specifications

The A1 Policy Management System (A1-PMS) plays a crucial role in managing policies and configurations within the O-RAN network architecture. As the O-RAN Alliance continually refines its specifications, it becomes essential to assess how well A1-PMS adheres to these evolving standards. In this discussion, I will make the comparison between the latest O-RAN API specifications and the upstream OpenAPI specifications utilized for implementing A1-PMS. Trying to examine the alignment, discrepancies, and potential areas for improvement.

Simple Comparison of OpenAPI Specifications

I identidy as
openapi-oran.yaml the specifications given by O-Ran Alliance revised on 31/03/2024
openapi.yaml the upstream openapi v3 specifications upstream in the /api folder 

Both OpenAPI specifications share similar high-level structures, including keys like `openapi`, `info`, `servers`, `paths`, and `components`. 

Paths Comparison

The main differnce in paths is based on the nesting pattern. There are multiple opinions on Nested Resources type of links. It helps with readability  but it can lead to long URLs or redundant endpoints because of less flexibility in paths.

So and edpoint:
/policytypes/{policyTypeId}/policies/{policyId}

can become with policyTypeId in the body
/policies/{policyId}

Analysis Topics

1. Limitations of JSON Schema:
   - JSON Schema Limitations:
     - Pros:
       - Standardized: JSON Schema provides a standardized way to define and validate the structure of JSON data.
       - Widely Supported: Many tools and libraries support JSON Schema, making it easy to integrate with various technologies.
     - Cons:
       - Expressiveness: JSON Schema may lack the expressiveness needed for complex validation rules, such as interdependent fields.
       - Readability: Large and complex schemas can become difficult to read and maintain.

2. Input/Output Parameters:
   - Optional Fields:
     - Pros:
       - Reusability: Using common models with optional fields allows for model reuse across different API endpoints.
       - Flexibility: Clients can send only the necessary data without being forced to include all optional fields.
     - Cons:
       - Dead Data: Unused optional fields may be sent by clients, leading to "dead" data that the server has to process or ignore.
       - Validation Complexity: Additional logic is required to handle the presence or absence of optional fields, increasing validation complexity.

3. Specific Schemas for Certain Calls:
   - Advantages:
     - Documentation: More specific examples can be provided for each operation, improving documentation clarity.
     - Generated Code: More accurate and efficient code generation, as the schemas are tailored to specific operations, reducing the need for extra checks.
   - Disadvantages:
     - Translation Effort: Similar objects may need to be translated between different schemas, requiring adapter/builder/transformer patterns in code.
     - Maintenance: Maintaining multiple specific schemas can increase the overall maintenance effort.

4. Generated Code and Contract Compliance:
   - Impact on Generated Code:
     - Changes in schemas will affect the generated interfaces, potentially requiring updates to implementations to ensure they comply with new contracts.
     - Specific schemas will result in more precise interfaces, reducing runtime errors but increasing development time for ensuring compliance.

Solutions Following Best Practices

1. Use Specific Schemas for Critical Operations:
   - Define specific schemas for different operations to improve clarity and reduce the risk of errors.
   - Use OpenAPI features such as `allOf`, `oneOf`, and `anyOf` to create flexible and reusable components without compromising specificity.

2. Implement Adapter Pattern for Code Adaptation:
   - Use the Adapter pattern to translate between different but similar objects, ensuring compliance with ORAN specifications without major code changes.

Pros and Cons of Java Patterns for Code Adaptation

All these solutions are viable, but will add complexity and abstraction to the code

- Adapter Pattern: Useful for converting one interface to another.
- Builder Pattern: Useful for constructing complex objects step-by-step.
- Transformer Pattern: Useful for converting objects from one type to another while keeping transformation logic separate from business logic.

Using OpenAPI Rules and Syntax for Code Adaptation

OpenAPI provides several features that can help in defining clear and adaptable specifications, we might want to investigate those to have some flexible solution for obejct declaring:

1. Using `allOf`, `oneOf`, `anyOf`: https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
   - Combine multiple schemas using `allOf` to create a new schema that includes all properties.
   - Use `oneOf` or `anyOf` to define schemas where only one or any combination of the listed schemas is valid, respectively.

   components:
     schemas:
       Policy:
         type: object
         properties:
           id:
             type: string
           name:
             type: string

       PolicyExtended:
         allOf:
           - $ref: '#/components/schemas/Policy'
           - type: object
             properties:
               description:
                 type: string

2. Discriminator for Polymorphism: https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/
   - Use the `discriminator` property to define inheritance and polymorphism in your schemas, allowing you to use a base schema with multiple derived schemas.

   components:
     schemas:
       BasePolicy:
         type: object
         discriminator:
           propertyName: type
           mapping:
             extended: '#/components/schemas/ExtendedPolicy'
         properties:
           id:
             type: string
           type:
             type: string
       
       ExtendedPolicy:
         allOf:
           - $ref: '#/components/schemas/BasePolicy'
           - type: object
             properties:
               description:
                 type: string

3. Extending and Overriding Schemas: (using 1)
   - Create new schemas by extending existing ones to avoid duplication and ensure consistency.

   components:
     schemas:
       BasePolicy:
         type: object
         properties:
           id:
             type: string
           name:
             type: string

       ExtendedPolicy:
         allOf:
           - $ref: '#/components/schemas/BasePolicy'
           - type: object
             properties:
               description:
                 type: string

4. Parameter and Response Reusability: (current)
   - Define reusable parameters and responses in the components section and reference them in different paths.

   components:
     parameters:
       PolicyId:
         name: policyId
         in: path
         required: true
         schema:
           type: string

   paths:
     /policies/{policyId}:
       get:
         parameters:
           - $ref: '#/components/parameters/PolicyId'

Schema Usage in Paths

Using allOf to Extend Objects

To avoid using the `required` flag directly and create more flexible schemas, we can use the allOf keyword to combine schemas. This allows you to create an extended schema from an original one without repeating required properties.

components:
  schemas:
    Policy:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    PolicyExtended:
      allOf:
        - $ref: '#/components/schemas/Policy'
        - type: object
          properties:
            description:
              type: string

public class Policy {

  private String id;
  private String name;
...
}

public class PolicyExtended {

  private String id;
  private String name;
  private String description;
...
}

OpenAPI Required Properties

In OpenAPI 3 by default, all object properties are optional. Required properties can be identified in the required list:  

components: 
  schemas:
    Policy:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id

Having required parameters has only one effect of genereted code, the tool generates only one construcotr with only default parameters. So the implementer can use the setters and getters.

  /**
   * Constructor with only required parameters
   */
  public Policy(String id, String name) {
    this.id= id;
  }

TODO and topic to follow

- Evaluate the necessity of optional fields: Determine if certain optional fields can be removed or if their use can be better documented to avoid dead data.
- Consider adopting more specific schemas for critical operations: This can improve both the documentation and the generated code quality. Leverage OpenAPI Features: Use OpenAPI's advanced features like `allOf`,
- Prepare for code adaptations: Implement patterns like Adapter/Builder/Transformer to handle translations between similar objects, facilitating easier maintenance and adaptation to specification changes.
- Regular compliance checks.