...

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.
Topics: optional parameters, what can be unimplementable
TODO: use v3 api spec

Simple Comparison of OpenAPI Specifications

I identidy as
openapi-oran.yaml the specifications given by O-Ran Alliance revised on 31/03/2024, and
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

...

openapi-oran.yaml 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

...

...

...

openapi.yaml Paths:

1. /a1-policy/v2/policy-instances
2. /a1-policy/v2/policy-types
3. /a1-policy/v2/policies/{policy_id}
4. /a1-policy/v2/configuration
5. /a1-policy/v2/services/{service_id}/keepalive
6. /a1-policy/v2/services
7. /a1-policy/v2/policy-types/{policytype_id}
8. /a1-policy/v2/policies
9. /a1-policy/v2/services/{service_id}
10. /a1-policy/v2/policies/{policy_id}/status

Components

openapi-oran.yaml Components:

• Schemas:
  1. PolicyObject
  2. PolicyStatusObject
  3. PolicyTypeObject
  4. ProblemDetails
  5. JsonSchema
  6. NotificationDestination
  7. PolicyId
  8. PolicyTypeId

openapi.yaml Components:

• Schemas:
  1. policy_type_definition
  2. error_information
  3. void
  4. status_info
  5. authorization_result
  6. ric_info
  7. service_registration_info
  8. policy_info_list
  9. policy_status_info
  10. service_status
  11. ric_info_list
  12. input
  13. policy_authorization
  14. policy_type_id_list
  15. policy_info
  16. policy_id_list
  17. service_status_list
  18. service_callback_info_v2

Simple Analysis

Paths Analysis

• Both specifications provide endpoints for managing policies and policy types, but the structure and naming conventions differ.
• openapi-oran.yaml has a simpler path structure centered around policytypes and nested resources within policytypes.
• openapi.yaml includes a more complex path structure under the /a1-policy/v2 prefix, indicating versioning and a potentially more hierarchical and service-oriented approach.

Components Analysis

• openapi-oran.yaml has a focused set of schemas primarily around policies (PolicyObject, PolicyStatusObject, PolicyTypeObject) and identifiers.
• openapi.yaml has a more extensive and varied set of schemas including policy information, service registration, suggesting a broader scope.
• The schemas in openapi.yaml appear to cater to a more granular level of API operations with various status and info objects (policy_status_info, service_status, ric_info_list).

Summary

...

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;
  }

Handling serviceId in Request Bodies and Bearer Tokens

Current Implementation

In the current implementation, the `serviceId` can be set in the body of a request and is defined as optional. The default value for `serviceId` in `PolicyObjectInformation` (PolicyApi) is a space, which accommodates cases where the `serviceId` might be missing. However, in the `ServiceApi`, the `serviceId` is required, for example, when creating a service.

Ideal Implementation

The use of a space as a default value for `serviceId` is a workaround to handle missing IDs. Ideally, the `serviceId` should be extracted from a bearer token. This can be done by decoding a JWT token using built-in Java functions.

Here’s a sample code snippet to decode a JWT token and extract the `serviceId`:

String token = getAuthToken(receivedHttpHeaders);
String[] chunks = token.split("\\.");
Base64.Decoder decoder = Base64.getUrlDecoder();
String payload = new String(decoder.decode(chunks[1]));
JsonObject jsonObject = new JsonObject();
jsonObject.add("payload", JsonParser.parseString(payload));
String serviceId = jsonObject.getAsJsonObject("payload").get("serviceId").getAsString(); //if the json token has the field serviceId

Integrating with Existing Code

In the codebase, there is already a function to get the token located in the class:

org.onap.ccsdk.oran.a1policymanagementservice.controllers.authorization.AuthorizationCheck

String getAuthToken(Map<String, String> httpHeaders)

Bearer Token in Headers

The bearer token would be passed during the API call via headers as follows:

"Authorization: Bearer <bearer_token>"

By extracting the serviceId from the bearer token, we can ensure that the `serviceId` is always available and accurate, enhancing the security and reliability of the API.

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

...

.

...

...