Define configuration files

Ocean loads resources from the .port directory when the integration starts. The scaffold creates this layout:

my-integration/
└── .port/
    ├── spec.yaml
    └── resources/
        ├── blueprints.json
        └── port-app-config.yaml

File	Required	Role
spec.yaml	Yes	Integration type, supported kinds, user config schema, and features.
resources/blueprints.json	No	Default blueprints created or updated on start (when initializePortResources is enabled).
resources/port-app-config.yaml	No	Default mapping for those kinds.

File names

Scaffolds may use .yaml or .yml. Use the names your scaffold generated.

spec.yaml

spec.yaml declares how Port presents the integration and which parameters users must provide.

Typical sections:

.port/spec.yaml

type: myIntegration
description: My integration for Port
icon: Default

features:
  - type: exporter
    section: Other
    resources:
      - kind: my-kind

configurations:
  - name: apiBaseUrl
    required: true
    type: url
    description: Base URL of the third-party API
  - name: apiToken
    required: true
    type: string
    sensitive: true
    description: API token for the third-party API

Field	Purpose
type	Integration type identifier (also used for image naming conventions).
features[].resources	Kinds your resync handlers support.
configurations	User-facing parameters. Validated at startup. See configuration validation.

For each configurations entry, set name (camelCase), required, type (string, integer, boolean, object, url, and related types), description, and sensitive when the value is a secret.

Default blueprints and mapping

blueprints.json and port-app-config.yaml are optional. When present and initializePortResources is true (default), Ocean creates or updates them in Port on start.

Author mapping so that:

• Each kind matches a @ocean.on_resync handler (or a live event kind you support).
• JQ expressions read fields from the raw objects your code yields.
• Users can later edit the mapping in Port without changing your integration code.

See configure mapping for mapping structure and JQ patterns.

Changing defaults after install

After the first install, changing .port/resources/ on disk does not always overwrite what is already in Port. Update blueprints and mapping in the Port UI or API when the integration is already installed.

Next steps

• Implement an API client.
• Kinds and selectors if you need custom mapping fields.