bisslog-schema 0.0.9

It is a lightweight framework to organize and document the key elements of a distributed system, focusing on its use cases and service design. It structures the metadata without exposing any underlying technical or implementation-specific details.

bisslog-schema-py

bisslog-schema-py is a lightweight framework to organize and document the key elements of a distributed system, focusing on its use cases and service design.
It structures the metadata without exposing any underlying technical or implementation-specific details. The goal is to design and document a distributed system from a service-centric perspective, emphasizing business use cases and their criticality, while remaining technology-agnostic.

🚀 Installation

You can install bisslog-schema using pip:

pip install bisslog_schema

For YAML support, you may also need to install PyYAML:

pip install bisslog_schema[yaml]

or

pip install pyyaml

---

Example YAML for Service Definition

Here is an example of how to define a service and its use cases using YAML:

---
name: "webhook receiver"
type: "microservice"
description: "Receives events from external platforms and converts them into company events for internal processing"
service_type: "functional"
team: "code-infrastructure"
tags:
  service: "webhook-receptor"

use_cases:
  addEventAdmitted:
    name: "add event type admitted to platform"
    description: "Updates adding event type admitted to platform if not exists, otherwise updates"
    triggers:
      - type: "http"
        options:
          route: "/webhook/event-type-admitted/{uid}"
          apigw: "internal"
          authenticator: "employee"
          method: "post"
          mapper:
            path_query.uid: uid
            body: data
            headers.user: creator
    external_interactions:
        - keyname: "marketing_division"
          type_interaction: "database"
          operation: "get_last_sales_from_client"
  # More use cases...

Note: The criticality field can use either named levels (e.g., "high") or direct numeric values (e.g., 90).

---

🔧 CLI Usage

Validate metadata files through the command line, ensuring they conform to the expected schema.

bisslog_schema analyze_metadata service.yaml --format-file yaml

Options

• --path: Specify the path to the metadata file. If not provided, it will search in the default locations.
• --format-file: Specify the format of the metadata file. Supported formats are yaml and json. Default is yaml.
• --encoding: File encoding (default: utf-8)
• --min-warnings: Minimum warning percentage (optional)

---

💻 Loading Service Metadata

You can load service definitions from YAML or JSON files using the read_service_metadata function.
It automatically searches for metadata files in predefined locations if a path is not provided.

You can specify the path to the metadata file as an argument or as an environment variable in SERVICE_METADATA_PATH.

Example

from bisslog_schema import read_service_metadata

service_info = read_service_metadata()
print(service_info.name)
for use_case_keyname, use_case in service_info.use_cases.items():
    print(f"{use_case.keyname}: {use_case.name}")

---

Main Concepts

ServiceInfo

The ServiceInfo class models a service in the system.
Each service can define:

• name: Service name
• description: Brief explanation of the service's responsibility
• type: Logical category (e.g., "microservice", "library")
• service_type: Service type (e.g., "functional", "technical")
• team: Responsible team
• tags: Arbitrary metadata tags for classification
• use_cases: List of UseCaseInfo objects representing the service's use cases

Service metadata can be loaded dynamically from external YAML or JSON files.

Service Definition Example:

The following example illustrates a service definition with its use cases and external interactions:

This is the YAML representation of the service definition:

---
name: "user management"
type: "microservice"
description: "Handles creation, update, and retrieval of user accounts in the system"
service_type: "functional"
team: "identity-platform"
tags:
  service: "user-management"

use_cases:
  registerUser:
    name: "register user"
    description: "Registers or creates a new user in the system"
    actor: "end user"
    criticality: "high"
    type: "create functional data"
    triggers:
      - type: "http"
        options:
          route: "/user"
          method: "post"
          apigw: "customer-public"
          mapper:
            body: user_data
    external_interactions:
      - keyname: users_division
        type_interaction: "database"
        operation: "create_user"
    tags:
      accessibility: "public"

---

UseCaseInfo

The UseCaseInfo class represents a use case belonging to a service, with the following fields:

• keyname: Unique identifier for the use case.
• name: Human-readable name.
• description: A detailed description of what the use case does.
• actor: The entity (user, system, platform) that initiates the use case.
• type: Logical operation type (e.g., "create", "read", "update", "delete").
• criticality: Business importance of the use case, represented as a CriticalityEnum.
• tags: Metadata tags for further classification.
• triggers: List of TriggerInfo entries defining how the use case is triggered.
• external_interactions: List of ExternalInteraction Represents any external systems or APIs this use case depends on or interacts with.

---

TriggerInfo and TriggerOptions

Triggers define how a use case is initiated.
Available trigger types (enumerated by TriggerEnum) include:

• HTTP: HTTP request initiation.
• WebSocket: WebSocket-based interaction.
• Consumer: Event-driven trigger (e.g., queues).
• Schedule: Time-based scheduled triggers.

Each trigger may have associated options (e.g., route, method, authenticator).

---

ExternalInteraction

ExternalInteraction

The ExternalInteraction class represents an external interaction in the system, such as database access or external service calls.

• keyname: Unique identifier for the interaction. For example, marketing_division.
• type_interaction: String representing the type of interaction (optional). For example, database.
• operation: Specific operation or action being performed (optional). For example, get_last_sales_from_client.
• type_interaction_standard: Standardized type of interaction resolved from type_interaction using aliases (optional).

Example of External Interaction:

use_cases:
  addEventAdmitted:
    external_interactions:
        - keyname: "marketing_division"
          type_interaction: "database"
          operation: "get_last_sales_from_client"

---

CriticalityEnum

CriticalityEnum provides a standardized set of criticality levels for use cases:

Level	Value
NONE	0
VERY_LOW	10
LOW	20
MEDIUM	50
HIGH	70
VERY_HIGH	90
CRITICAL	100

This scale helps prioritize use cases based on their business or operational impact.

Why use bisslog-schema-py?

• Technology-agnostic: Focus on service and use case modeling, independent of the underlying implementation.

• Organized metadata: Centralizes your distributed system documentation.

• Extensible: Easily expandable with new fields and trigger types.

• Integration-friendly: Can be used for CI/CD validation or automated documentation generation.

🧪 Running library tests

To Run test with coverage

coverage run --source=bisslog_schema -m pytest tests/

To generate report

coverage html && open htmlcov/index.html

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.