Definition of connector mapping for .frog programs
FROG — Free Open Graphical Language
- 1. Overview
- 2. Purpose of the Connector
- 3. Location in a .frog file
- 4. Relationship with the Interface
- 5. Connector Structure
- 6. Perimeter Slot Model
- 7. Port Mapping
- 8. Examples
- 9. Validation Rules
- 10. Extensibility
- 11. Summary
The connector section defines how a Frog is graphically represented when it is instantiated as a node inside another diagram.
The connector does not define the logical contract of the Frog. That responsibility belongs to the interface section.
Instead, the connector provides a deterministic graphical mapping from public interface ports to visible connection points around the node boundary.
A Frog may be executable without a connector. The connector becomes relevant when the Frog is intended to be reused as a graphical node.
This document also does not define repository-wide version policy. Top-level spec_version identifies the source-format compatibility target of the containing .frog file, while the published specification corpus version remains governed centrally in Versioning/Readme.md.
The connector provides:
- a consistent graphical representation of a Frog when reused as a node
- a deterministic mapping between public interface ports and visible connection points
- a simple, tool-independent connector layout model
The connector ensures that:
- ports appear in predictable locations
- graphical reuse remains stable across tools
- the visual shape of a reusable Frog remains independent from its internal diagram layout
The connector is defined as a top-level object.
Example structure:
{
"spec_version": "0.1",
"metadata": {},
"interface": {},
"connector": {},
"diagram": {},
"front_panel": {}
}
The connector section is optional.
It SHOULD be present when the Frog is intended to be instantiated as a reusable node inside another Frog.
A top-level executable Frog may omit the connector entirely.
In this source shape:
- top-level
spec_versionidentifies the source-format compatibility target of the file, connectordefines optional graphical projection of the public contract,- the published specification corpus version remains governed centrally in
Versioning/Readme.md.
The connector depends on the interface section.
The interface defines the public logical ports of the Frog. The connector defines where those ports appear on the node perimeter when the Frog is reused graphically.
Therefore:
- the connector MUST NOT introduce ports that do not exist in the interface
- the connector MUST reference only public interface ports
- a Frog may have an interface without a connector
- a Frog MUST NOT define a connector without an interface
In practical terms:
- interface = public contract
- connector = graphical projection of that contract
The connector does not define source-format compatibility policy and does not redefine the versioning meaning of top-level spec_version.
Example connector definition:
"connector": {
"granularity": 40,
"ports": [
{ "interface_port": "a", "slot": 34 },
{ "interface_port": "b", "slot": 36 },
{ "interface_port": "result", "slot": 14 }
]
}
Fields:
- granularity: number of discrete connector positions along the perimeter
- ports: mapping between public interface port identifiers and perimeter slots
If granularity is omitted, implementations SHOULD assume the default value of 40.
For FROG v0.1, the canonical model is a square node with a perimeter divided into 40 slots, that is 10 slots per side.
The connector is defined on a normalized square node boundary.
Slots are ordered clockwise starting from the top-left corner.
With the default granularity of 40, the perimeter is divided into four equal sides:
- Top side: slots
0..9 - Right side: slots
10..19 - Bottom side: slots
20..29 - Left side: slots
30..39
Conceptual model:
0 1 2 3 4 5 6 7 8 9
● ● ● ● ● ● ● ● ● ●
39 ● ● 10
38 ● ● 11
37 ● ● 12
36 ● ● 13
35 ● ● 14
34 ● ● 15
33 ● ● 16
32 ● ● 17
31 ● ● 18
30 ● ● 19
● ● ● ● ● ● ● ● ● ●
29 28 27 26 25 24 23 22 21 20
Each slot represents one discrete connection position on the perimeter of the reusable node.
The connector model defines logical placement only. Actual pixel rendering is implementation-dependent.
Each entry in connector.ports maps one public interface port to one connector slot.
Example:
{
"interface_port": "temperature",
"slot": 12
}
Fields:
- interface_port: id of a public port declared in the interface
- slot: connector slot index on the node perimeter
The slot determines where the corresponding connection point appears when the Frog is drawn as a reusable node.
The connector does not redefine port type, direction, or semantics. Those properties remain defined by the interface.
"connector": {
"granularity": 40,
"ports": [
{ "interface_port": "a", "slot": 34 },
{ "interface_port": "b", "slot": 36 },
{ "interface_port": "result", "slot": 14 }
]
}
"connector": {
"granularity": 40,
"ports": [
{ "interface_port": "enable", "slot": 1 },
{ "interface_port": "setpoint", "slot": 3 },
{ "interface_port": "measurement", "slot": 6 },
{ "interface_port": "output", "slot": 22 }
]
}
{
"spec_version": "0.1",
"metadata": {},
"interface": {
"inputs": [
{ "id": "file_path", "type": "string" }
],
"outputs": [
{ "id": "status", "type": "bool" }
]
},
"diagram": {},
"front_panel": {}
}
In this case, the Frog remains executable, but it does not yet define a reusable graphical connector.
In this example:
- top-level
spec_versionidentifies the source-format compatibility target of the file, - the absence of
connectormeans no serialized reusable-node perimeter mapping is provided, - the published specification corpus version remains governed centrally in
Versioning/Readme.md.
Implementations MUST enforce the following rules:
- the connector MUST be a top-level object when present
- each connector entry MUST reference an existing public interface port
- slot values MUST satisfy
0 ≤ slot < granularity - each connector slot MUST be used at most once
- each interface port referenced in the connector MUST appear at most once
Additionally, for a Frog declared or interpreted as a reusable graphical node:
- every public interface input SHOULD have a connector mapping
- every public interface output SHOULD have a connector mapping
Implementations MAY treat incomplete mappings as validation errors when full graphical reusability is required.
Invalid connector mappings MUST trigger validation errors.
These checks validate optional connector structure and connector-to-interface consistency.
They do not, by themselves, redefine top-level spec_version policy or repository-wide corpus-version governance.
Tools MAY extend connector entries with additional non-semantic properties.
Example:
{
"interface_port": "speed",
"slot": 8,
"label": "Speed Input"
}
Such properties MAY be used for authoring, visualization, or editor hints.
Unknown connector properties MUST be ignored by runtimes and by tools that do not support them.
Such extensions should remain compatible with the centralized cumulative version model: later source-format versions should normally extend earlier valid connector forms rather than silently replace them, unless an explicit breaking boundary is declared in repository-wide version governance.
The connector defines how a Frog appears when it is reused as a node inside another diagram.
It does not define the logical contract of the Frog. That responsibility belongs to the interface.
The connector provides:
- a deterministic connector placement model
- a simple and standardized perimeter slot layout
- a clear separation between logical public ports and graphical node representation
In short:
- interface defines what the Frog exposes
- connector defines how that interface appears when the Frog is used as a reusable node
- connector does not define source-format compatibility law or published specification corpus versioning