Référence de la configuration

Format

La configuration est un objet JSON, encodé en base64url (alphabet A-Z a-z 0-9 - _, sans remplissage =) après conversion en UTF-8, et placé dans l’attribut data-annuaire-config de l’extrait, ou après le # de l’adresse du cadre. Les espaces et retours à la ligne qu’un éditeur insérerait dans la valeur sont ignorés.

{
  "v": 1,
  "zone": { "type": "commune", "code": "33243" },
  "thematiques": ["logement-hebergement", "difficultes-financieres"],
  "favoris": { "services": ["78f07f9ea9"] },
  "masques": { "structures": ["9c6260d40e"] },
  "titre": "Aides et services à Libourne",
  "couleur": "#1e6fd9"
}

Les champs vides sont omis : le configurateur n’écrit ni liste vide, ni titre ou couleur absents. L’exemple minimal est {"v":1,"zone":{"type":"commune","code":"33243"}}, qui donne eyJ2IjoxLCJ6b25lIjp7InR5cGUiOiJjb21tdW5lIiwiY29kZSI6IjMzMjQzIn19.

Clés

Clé	Type	Obligatoire	Valeurs	Effet
v	nombre	oui	1	Version du schéma. Une version majeure inconnue donne un message discret dans la page, jamais un bloc cassé.
zone.type	texte	oui	commune, epci, departement	Nature du territoire.
zone.code	texte	oui	code INSEE de la commune, SIREN de l’intercommunalité, code du département (01 à 95, 2A, 2B, 971 à 976)	Le territoire. Une commune affiche les services sur place et ceux ouverts à ses habitants depuis ailleurs ; une intercommunalité, ceux de toutes ses communes ; un département, ceux qui y sont implantés ou ouverts à tout le département.
thematiques	liste de textes	non	voir ci-dessous	Besoins affichés. Liste vide ou absente : tous. Un service est retenu s’il relève d’au moins un des besoins listés.
favoris.services	liste de textes	non	identifiants de services	Mis en avant en tête de liste, dans l’ordre donné, avec la mention « Mis en avant ».
favoris.structures	liste de textes	non	identifiants de structures	Tous les services de ces structures sont mis en avant.
masques.services	liste de textes	non	identifiants de services	Retirés de l’affichage.
masques.structures	liste de textes	non	identifiants de structures	Tous les services de ces structures sont retirés.
titre	texte	non	120 caractères au plus	Titre du widget. Absent : « Aides et services à ».
couleur	texte	non	#rrggbb	Couleur d’accent des boutons, liens et pastilles actives. Assombrie automatiquement si elle ne tient pas un contraste de 4,5:1 sur le fond du widget. Une valeur qui n’est pas une couleur est ignorée.

Une liste plate dans favoris ou masques ("favoris": ["78f07f9ea9"]) est acceptée et lue comme une liste de services.

Besoins

Les seize besoins, plus « autres » pour les services qui n’en déclarent aucun :

choisir-un-metier, creer-une-entreprise, difficultes-administratives-ou-juridiques, difficultes-financieres, equipement-et-alimentation, famille, lecture-ecriture-calcul, logement-hebergement, mobilite, numerique, preparer-sa-candidature, remobilisation, sante, se-former, souvrir-a-linternational, trouver-un-emploi, autres. Un besoin absent de cette liste est ignoré.

Ce sont les racines des thématiques de data·inclusion ; le référentiel complet est publié en JSON à https://annuairesolidaire.fr/api/v1/referentiels/thematiques.json.

Identifiants

Les identifiants de services et de structures sont ceux de l’annuaire : dix caractères hexadécimaux, stables d’une semaine à l’autre, visibles dans l’adresse de chaque fiche (https://annuairesolidaire.fr/services/78f07f9ea9-…/) et dans l’index de chaque zone (https://annuairesolidaire.fr/api/v1/zones/communes/33243.json). Le configurateur les relève pour vous quand vous mettez en avant ou masquez une carte dans l’aperçu.

Une fiche peut disparaître des données : son identifiant dans masques est alors ignoré (au pire, rien ne change), son identifiant dans favoris aussi, mais une mise en avant disparaît sans bruit. Le bouton « Vérifier ma configuration » du configurateur liste ces références mortes.

Compatibilité

À l’intérieur de la version 1, le schéma ne fait qu’ajouter des clés facultatives : un extrait posé aujourd’hui reste valide. Un changement incompatible donnerait une version 2 du schéma et du script (/widget/v2.js), la version 1 continuant de fonctionner. Les changements sont consignés dans les nouveautés.