Intent Manifest - Fields and Spec

[anshulsao]

Premise:
As we progress in our journey with Infrastructure as Catalog (InCa), having established the ability to create resources using intent definitions, our next pivotal step involves solidifying the manifest definition. The objective of this discussion is to finalize the standard fields that should be present in the manifest to accurately and effectively define an intent.

Introduction:
The manifest is crucial as it acts as a blueprint, guiding the realization of resources in alignment with the predefined intents within InCa, independent of specific environments. Establishing a standardized set of fields for the manifest is vital to ensure consistency, clarity, and accuracy across various implementations.

Key Considerations:

Clarity and Simplicity: The fields should be easy to understand and use, ensuring that users can define intents without ambiguity.
Flexibility: The manifest should accommodate a range of intents and implementations, providing users with the adaptability to define various resources.
Scalability: As projects and implementations evolve, the manifest should be able to support growth and complexity without becoming cumbersome.
Compatibility: Ensure that the manifest fields are compatible with various implementations and do not restrict the use of different technologies or platforms.

Discussion Points:

Field Definitions: What should be the mandatory and optional fields within the manifest to adequately define an intent?
Data Types: What types of data will the fields hold, and how will they be validated?
Hierarchy and Structure: How should the fields be structured to ensure logical and hierarchical definition of the intents?
Implementation Specifics: How will the manifest accommodate implementation-specific details without compromising the generality of the intent?
Environment Overrides: How should the manifest allow for environment-specific overrides while maintaining the integrity of the original intent?

[anshulsao]

Let's take the first step to make a clear and easy-to-follow plan that everyone can stick to by using JSON schema definitions for each intent. This means we'll lay out all the important fields, their types of data, and possible values using a JSON schema. By keeping this schema in a special Git repository, we make sure everyone in the community can understand it easily and also make it simple to keep it updated. Plus, this method helps users by offering auto-complete options and information about each field right in their favorite IDEs, making it user-friendly and easy to access.

We'll talk about where to place our Git repository and how we'll keep it updated, along with how we'll manage different versions of it, in a future discussion.

[anshulsao]

Advantages:

Standardization: Utilizing a JSON schema for each intent ensures a standardized approach to defining fields and data types, promoting consistency across various intents and implementations.
Community Collaboration: Housing the schema definition in a Git repository encourages community collaboration, allowing for collective enhancement and evolution of the schema.
User-Friendly: The approach enhances user experience by providing auto-complete and documentation within IDEs, making it easier to work with the schema and reducing the likelihood of errors.
Transparency: Maintaining the schema in a public repository ensures transparency and allows users to understand the evolution of schema definitions, contributing to trust and reliability.

[rr0hit]

• Why not yamls?
• Would we need to maintain an index for ease of access say like index.yml in helm repos

[rr0hit]

WRT directory structure, I'd suggest having some on the basis of maturity say alpha, beta, GA.

[pramodh-ayyappan]

For spec we need to define more reusable schemas as per the kind. Like traits what we call in our schemas repo.

[anshulsao]

Suggestion for Resource JSON Structure

Field	Type	Description
metadata	Object	Contains descriptive and auxiliary information.
kind	String	Describes the intent/kind of the resource.
spec	Object	Detailed information about the resource.
disabled	Boolean	Indicates if the resource is disabled (true) or enabled (false) by default.
flavor	Object	Specifies the default implementation details.
advanced	Object	Contains flavor-specific specifications.

metadata Object

Field	Type	Description
maintainer	String	The person/team maintaining the resource.
documentation_link	String	Link to the resource documentation.
tags	Array	Keywords related to the resource.
name	String	The name of the resource.
description	String	A brief description of the resource.

flavor Object

Field	Type	Description
version	String	The version of the default implementation.
name	String	The name of the default implementation.

advanced Object

• [FlavorName]: Specifications and configurations related to a particular flavor.
  • Type: Object
  • Description: Contains attributes and configurations specific to the flavor named [FlavorName].
  • Sub-fields: Vary depending on the flavor.

[FlavorName] Object Example

Field	Type	Description
attributeA	String	Description of attribute A.
attributeB	String	Description of attribute B.

Note: The fields within each flavor in the advanced section may vary based on the specific requirements and configurations of that flavor.

[rr0hit]

• While version makes sense inside the flavor block, we might need a version at the schema level too. Say we have to make breaking changes to the schema at some point, user must be aware of what version he is using.

[rr0hit]

"disabled" is a manifestation level concern, does it lie in the catalog?

[rr0hit]

One of the use cases to use disabled is to keep elements disabled until we'll tested. But then it is best represented as different versions of the same catalog. The other use case is for optional resources.

In any case should'nt it be "enabled": true/false

[anurag-facets]

+1 for using "enabled:true" rather than "disabled:true"

[rr0hit]

We need to answer "What qualifies to be in spec?"