ASIMOV Module Manifest Specification (MMS)

1. Introduction

The [ASIMOV] Platform is a polyglot development platform for trustworthy, neurosymbolic AI.

This specification defines the ASIMOV Module Manifest format, a YAML-based declarative format for describing ASIMOV Platform modules. Module manifests provide metadata about modules including their capabilities, dependencies, and the resources they handle. This enables the ASIMOV Platform to automatically discover, configure, and orchestrate modules based on their declared capabilities.

1.1. Overview

The ASIMOV Module Manifest Specification defines a standardized format for declaring module metadata, capabilities, and requirements within the ASIMOV Platform ecosystem. Module manifests enable:

• Automatic Discovery: Modules can be automatically discovered and registered based on their manifest declarations

• Capability Advertisement: Modules declare what programs they provide and what resources they can handle

• Dependency Resolution: The platform can resolve module dependencies and ensure required capabilities are available

• Configuration Management: Manifests provide a single source of truth for module configuration

1.2. Scope

This specification covers:

• The syntax and structure of module manifest files

• Required and optional manifest fields

• Validation rules and constraints

• Processing model for manifest interpretation

This specification does not cover:

• The runtime behavior of modules

• Inter-module communication protocols

• Platform-specific implementation details

1.3. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

A conforming module manifest is one that satisfies all the requirements defined in this specification.

A conforming manifest processor is one that correctly interprets module manifests according to the processing model defined in this specification.

2. Manifest Structure

2.1. File Format

Module manifests MUST be written in YAML 1.2 format [YAML]. The manifest file MUST be named module.yaml and placed in the .asimov directory in the root of the module repository (i.e., .asimov/module.yaml).

The manifest MUST begin with a YAML document separator (---) and MAY include the following comment referencing this specification:

# See: https://asimov-specs.github.io/module-manifest/
---

2.2. Top-Level Fields

A module manifest consists of the following top-level fields:

2.3. The name Field

The name field MUST contain a string that uniquely identifies the module within the ASIMOV Platform. The name:

• MUST consist only of lowercase letters, digits, and hyphens

• MUST start with a letter

• MUST NOT exceed 64 characters in length

• SHOULD be descriptive and follow the pattern category-provider-type (e.g., search-google-fetcher)

2.4. The label Field

The label field contains an optional human-readable display name for the module. If provided, it SHOULD be concise and suitable for display in user interfaces.

2.5. The summary Field

The summary field contains an optional brief description of the module’s purpose and functionality. This SHOULD be a single sentence that clearly explains what the module does.

2.6. The links Field

The links field contains an optional array of URLs pointing to resources related to the module, such as:

• The module’s homepage

• Source code repository

• Documentation

• Package registry entries

All URLs in this array MUST be well-formed and use HTTPS where applicable.

2.7. The provides Section

The provides section declares the capabilities that a module makes available to the platform. Currently, the following capability types are defined:

2.7.1. programs

The programs field contains an array of executable program names that the module provides. These programs:

• MUST follow the naming convention asimov-{module}-{function}

• MUST be executable files or scripts included with the module

• SHOULD implement well-defined interfaces for their function type as specified in [ASIMOV-PPS]

The function types (e.g., fetcher, importer, emitter, processor) are defined in the ASIMOV Program Patterns Specification.

Example:

provides:
  programs:
    - asimov-serpapi-fetcher
    - asimov-serpapi-importer

2.8. The handles Section

The handles section declares what types of resources or inputs the module can process. Multiple handler types can be specified:

2.8.1. url_protocols

An array of URL protocol schemes (without the trailing colon) that the module can handle.

Example:

handles:
  url_protocols:
    - near
    - ipfs

2.8.2. url_prefixes

An array of URL prefixes that the module can handle. These MUST be complete URLs including the protocol scheme.

Example:

handles:
  url_prefixes:
    - https://amazon.com/
    - https://ebay.com/itm/

2.8.3. url_patterns

An array of URL patterns with parameter placeholders that the module can handle. Patterns MUST conform to the syntax defined in [URLPATTERN].

Example:

handles:
  url_patterns:
    - https://google.com/search?q=:query
    - https://x.com/:account/followers

2.8.4. file_extensions

An array of file extensions (including the leading dot) that the module can process. File extensions SHOULD be registered with IANA as specified in [RFC6838] or be well-established conventional extensions.

Example:

handles:
  file_extensions:
    - .csv
    - .xlsx

2.8.5. content_types

An array of MIME content types that the module can process. Content types MUST be formatted according to [RFC2046] and SHOULD be registered in the IANA Media Types registry [IANA-MEDIA-TYPES].

Example:

handles:
  content_types:
    - application/json
    - text/csv

3. Examples

3.1. Basic Module Manifest

A minimal module manifest for a template module:

# See: https://asimov-specs.github.io/module-manifest/
---
name: template
label: Template
summary: Fork this to create your own module!
links:
  - https://github.com/asimov-modules/asimov-template-module
  - https://crates.io/crates/asimov-template-module

provides:
  programs:
    - asimov-template-emitter

handles:
  url_protocols:
  url_prefixes:
  url_patterns:
  file_extensions:
  content_types:

3.2. Search API Module

A module that provides search capabilities through multiple search engines:

---
name: serpapi
label: SerpAPI Search
summary: Provides search results from multiple search engines via SerpAPI
links:
  - https://serpapi.com
  - https://github.com/asimov-modules/asimov-serpapi-module

provides:
  programs:
    - asimov-serpapi-fetcher
    - asimov-serpapi-importer

handles:
  url_patterns:
    - https://bing.com/search?q=:query
    - https://duckduckgo.com/?q=:query
    - https://google.com/search?q=:query
    - https://baidu.com/s?wd=:query

3.3. Social Media Scraper Module

A module that handles various social media platforms:

---
name: brightdata
label: Bright Data Scraper
summary: Web scraping for e-commerce and social media platforms
links:
  - https://brightdata.com
  - https://github.com/asimov-modules/asimov-brightdata-module

provides:
  programs:
    - asimov-brightdata-fetcher
    - asimov-brightdata-importer
    - asimov-brightdata-analyzer

handles:
  url_prefixes:
    - https://facebook.com/events/
    - https://facebook.com/groups/
    - https://facebook.com/marketplace/item/
    - https://instagram.com/
    - https://instagram.com/p/
    - https://instagram.com/reel/
    - https://linkedin.com/company/
    - https://linkedin.com/in/
    - https://x.com/
    - https://youtube.com/@
    - https://youtube.com/watch?v=

3.4. Blockchain Module

A module that handles blockchain protocols:

---
name: near
label: NEAR Protocol
summary: Integration with the NEAR blockchain ecosystem
links:
  - https://near.org
  - https://github.com/asimov-modules/asimov-near-module

provides:
  programs:
    - asimov-near-fetcher
    - asimov-near-validator
    - asimov-near-signer

handles:
  url_protocols:
    - near
  url_patterns:
    - https://explorer.near.org/accounts/:account
    - https://explorer.near.org/transactions/:txhash

4. Processing Model

4.1. Discovery

The ASIMOV Platform discovers modules by:

1. Scanning designated module directories for .asimov/module.yaml files

2. Validating each manifest according to this specification

3. Registering valid modules in the platform’s module registry

4.2. Validation

A manifest processor MUST validate that:

1. The manifest is valid YAML 1.2

2. All required fields are present

3. Field values conform to their specified types

4. The name field meets the naming requirements

5. All URLs in the links field are well-formed

6. Program names in provides.programs follow the naming convention

7. URL prefixes and patterns in the handles section are well-formed

4.3. Conflict Resolution

When multiple modules declare handlers for overlapping resources:

1. More specific handlers take precedence over less specific ones

2. url_patterns take precedence over url_prefixes

3. url_prefixes take precedence over url_protocols

4. For equal specificity, the platform MAY use additional criteria (e.g., module priority, user preference)

4.4. Runtime Behavior

When the platform needs to handle a resource:

1. It queries the module registry for modules that handle the resource type

2. It selects the most appropriate module based on the conflict resolution rules

3. It invokes the appropriate program from the module’s provides.programs list

4. The program processes the resource and returns results in the expected format

5. RDF Mapping

Module manifests can be mapped to RDF using YAML-LD [YAML-LD] or JSON-LD [JSON-LD]. This enables integration with linked data systems and semantic web technologies.

5.1. Vocabulary

This specification defines the following RDF vocabulary with the base IRI https://asimov-specs.github.io/module-manifest/:

5.2. Type Mappings

The following RDF types are defined:

• mms:Module - The class of ASIMOV modules

• mms:Program - The class of executable programs

• mms:Handler - The class of resource handlers

5.3. Property Mappings

Module manifest fields map to RDF properties as follows:

5.4. JSON-LD Context

The following JSON-LD context SHOULD be used when converting module manifests to JSON-LD:

{
  "@context": {
    "@vocab": "https://asimov-specs.github.io/module-manifest/",
    "mms": "https://asimov-specs.github.io/module-manifest/",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",

    "name": "mms:name",
    "label": "rdfs:label",
    "summary": "rdfs:comment",
    "links": {
      "@id": "rdfs:seeAlso",
      "@type": "@id"
    },
    "provides": "mms:provides",
    "programs": {
      "@id": "mms:providesProgram",
      "@container": "@set"
    },
    "handles": "mms:handles",
    "url_protocols": {
      "@id": "mms:handlesProtocol",
      "@container": "@set"
    },
    "url_prefixes": {
      "@id": "mms:handlesPrefix",
      "@type": "@id",
      "@container": "@set"
    },
    "url_patterns": {
      "@id": "mms:handlesPattern",
      "@container": "@set"
    },
    "file_extensions": {
      "@id": "mms:handlesExtension",
      "@container": "@set"
    },
    "content_types": {
      "@id": "mms:handlesContentType",
      "@container": "@set"
    }
  }
}

5.5. Example RDF Mapping

Given the following module manifest:

---
name: serpapi
label: SerpAPI Search
summary: Provides search results via SerpAPI
links:
  - https://serpapi.com

provides:
  programs:
    - asimov-serpapi-fetcher

handles:
  url_patterns:
    - https://google.com/search?q=:query

The equivalent RDF representation in Turtle would be:

@prefix mms: <https://asimov-specs.github.io/module-manifest/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

[] a mms:Module ;
   mms:name "serpapi" ;
   rdfs:label "SerpAPI Search" ;
   rdfs:comment "Provides search results via SerpAPI" ;
   rdfs:seeAlso <https://serpapi.com> ;
   mms:providesProgram "asimov-serpapi-fetcher" ;
   mms:handlesPattern "https://google.com/search?q=:query" .

6. Security Considerations

6.1. Manifest Validation

Implementations MUST:

• Validate all manifest fields before processing

• Reject manifests with malformed data

• Sanitize all string values to prevent injection attacks

• Verify that declared programs actually exist before registration

6.2. Program Execution

When executing programs declared in manifests:

• Programs SHOULD run with minimal required privileges

• The platform SHOULD implement sandboxing or containerization

• Resource limits SHOULD be enforced

• Network access SHOULD be restricted to declared URL patterns

6.3. URL Pattern Matching

URL pattern matching MUST be implemented carefully to avoid:

• Regular expression denial of service (ReDoS) attacks

• Unbounded memory consumption

• Pattern injection vulnerabilities

7. IANA Considerations

This specification does not require any IANA registrations.

8. Acknowledgments

The editors would like to thank the ASIMOV Platform community for their contributions and feedback during the development of this specification.

9. Changes

This section will document changes between versions of this specification.

9.1. Version 1.0

Initial version of the ASIMOV Module Manifest Specification.