{ "name": "Fenexity Technical Language", "abbreviation": "FTL", "version": "0.1.0", "status": "draft", "homepage": "https://semantics.fenexity.com", "lastUpdated": "2026-08-08", "informedBy": [ "ASD-STE100", "RFC 2119", "RFC 8174" ], "endpoints": { "rules": "https://semantics.fenexity.com/api/v0.1.0/ftl.json", "terms": "https://semantics.fenexity.com/api/v0.1.0/terms.json" }, "versioning": { "scheme": "Semantic Versioning for the whole FTL release", "patch": "wording clarification that does not intentionally change meaning", "minor": "new rules, new terms, new aliases, new examples", "major": "an incompatible change to an established rule or canonical meaning" }, "guidingPrinciple": "Reduce accidental ambiguity while preserving meaning, intent, context, and necessary technical complexity.", "coreStatement": "One concept, one canonical term. One canonical term, one defined meaning within a given context.", "principles": [ { "id": "P1", "title": "One preferred term for one concept", "statement": "Use one preferred term for one concept within a defined context." }, { "id": "P2", "title": "No stylistic variation", "statement": "Do not vary terminology for stylistic reasons." }, { "id": "P3", "title": "Explicit actors and actions", "statement": "Use explicit actors and actions." }, { "id": "P4", "title": "Short, structurally clear sentences", "statement": "Prefer short, structurally clear sentences." }, { "id": "P5", "title": "Explicit conditions", "statement": "State conditions explicitly." }, { "id": "P6", "title": "Preserve uncertainty", "statement": "Preserve uncertainty; do not strengthen a possibility into a requirement." }, { "id": "P7", "title": "Quantitative instead of vague", "statement": "Use quantitative statements instead of vague comparative language where practical." }, { "id": "P8", "title": "Preserve meaning and intent", "statement": "Preserve meaning and intent when summarizing or transforming information." } ], "writingRules": [ { "id": "FTL-W01", "title": "Use the preferred technical term", "rule": "When a concept has an established preferred term, use it instead of an alternative that means the same thing.", "avoid": "charger / charging device / charging point", "prefer": "EVSE (when that is the intended concept)", "note": "Check the FTL terminology data before choosing a term." }, { "id": "FTL-W02", "title": "Do not introduce synonyms for variation", "rule": "Technical documentation values semantic stability over prose variety. Do not alternate between equivalent words purely for style.", "avoid": "start ... begin ... initiate ... launch", "prefer": "start (once established)", "note": "Different words can make readers and agents ask whether different state transitions are meant." }, { "id": "FTL-W03", "title": "Use explicit subjects", "rule": "State who or what performs an action. Do not rely on implicit or ambiguous subjects.", "avoid": "It should then be updated.", "prefer": "The charging service SHOULD update the charging plan." }, { "id": "FTL-W04", "title": "State the condition before the action", "rule": "When a condition governs an action, state the condition first, then the action.", "avoid": "Enforce the local site power limit when the cloud connection is unavailable.", "prefer": "If the cloud connection is unavailable, the edge controller MUST enforce the local site power limit." }, { "id": "FTL-W05", "title": "Use concrete verbs", "rule": "Express actions as verbs. Avoid nominalization that obscures who does what.", "avoid": "The execution of validation occurs after initialization.", "prefer": "The service validates the configuration after it initializes." }, { "id": "FTL-W06", "title": "Avoid vague referents", "rule": "Review it, this, that, they, former, and latter when more than one referent is possible. Repeat the noun where needed.", "avoid": "The EVSE and the vehicle are connected. It starts charging.", "prefer": "The EVSE and the vehicle are connected. The vehicle starts charging.", "note": "The rewrite must keep the intended meaning." }, { "id": "FTL-W07", "title": "Do not hide requirements in descriptive prose", "rule": "Separate normative requirements from explanation. Do not bury MUST, SHOULD, or MAY statements in descriptive text." }, { "id": "FTL-W08", "title": "Use measurable properties instead of vague adjectives", "rule": "Avoid more robust, real-time, efficient, fast, reliable unless the relevant criterion is defined. State the measurable requirement.", "avoid": "The system reports faults reliably.", "prefer": "The system MUST report a blocking charging fault within 10 s after detection." }, { "id": "FTL-W09", "title": "Keep units explicit", "rule": "Do not use a bare number where the physical quantity or unit is necessary for interpretation.", "avoid": "Set the limit to 50.", "prefer": "Set the site power limit to 50 kW." }, { "id": "FTL-W10", "title": "Distinguish measurements, derived quantities, and estimates", "rule": "Do not present an estimate as a measurement or a derived quantity as a direct physical measurement. Label the semantic type when it matters.", "avoid": "The battery is at 80%.", "prefer": "The estimated State of Charge is 80%.", "note": "SoC is not the same semantic type as measured terminal voltage." }, { "id": "FTL-W11", "title": "Preserve source modality", "rule": "Do not transform can or could into SHOULD or MUST during rewriting or summarization. Keep the modality of the source.", "avoid": "The service could retry. becomes The service MUST retry.", "prefer": "The service could retry. becomes The service MAY retry, if the meaning permits." }, { "id": "FTL-W12", "title": "Preserve intent separately from implementation", "rule": "A requested mechanism is not automatically the underlying requirement. Record the intended outcome and the proposed mechanism separately when they differ." }, { "id": "FTL-W13", "title": "Use RFC normative terms consistently", "rule": "In normative Fenexity technical documents, use MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY with the meanings defined in RFC 2119 and RFC 8174.", "note": "Uppercase normative terms have normative meaning only in documents or sections that explicitly adopt this convention." }, { "id": "FTL-W14", "title": "Prefer established domain terminology", "rule": "Use OCPP, IEC, VDV, or software-engineering terminology where it accurately expresses the concept. Invent company terms only when no established term fits.", "avoid": "charger for EVSE", "prefer": "EVSE", "note": "Domain-specific technical nouns and verbs are permitted; they should come from the glossary, not from improvisation." }, { "id": "FTL-W15", "title": "Flag ambiguity instead of silently guessing", "rule": "If a term has multiple plausible technical meanings in the context, ask for clarification or explicitly state the interpretation you are using.", "avoid": "The PLC must be configured.", "prefer": "The Programmable Logic Controller must be configured. (state the intended meaning)" } ], "normativeTerms": [ { "term": "MUST", "meaning": "An absolute requirement of the specification." }, { "term": "MUST NOT", "meaning": "An absolute prohibition of the specification." }, { "term": "SHOULD", "meaning": "A recommended behavior. Valid reasons may exist to ignore it in particular circumstances, but the implications must be understood and weighed." }, { "term": "SHOULD NOT", "meaning": "A recommendation against a behavior. Valid reasons may exist to do it in particular circumstances, but the implications must be understood and weighed." }, { "term": "MAY", "meaning": "A permitted option. A document may choose whether to include the item." } ] }