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 ad 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'
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.
- 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: Ensure regular checks against ORAN specifications to stay compliant and make necessary adjustments in a timely manner.
- Adopt Specific Schemas: Use specific schemas for different API operations to improve clarity and reduce the risk of errors.
- Implement Adapter Pattern: Use the Adapter pattern to manage differences between similar objects, ensuring compliance with ORAN specifications.
- Leverage OpenAPI Features: Use OpenAPI's advanced features like `allOf`, `oneOf`, `anyOf`, and discriminators to create flexible and reusable components.