Zasady Nazewnictwa. Dokumentów XML Strona 1 z 9

Transkrypt

1 Zasady Nazewnictwa Dokumentów Strona 1 z 9

2 Spis treści I. Wstęp... 3 II. Znaczenie spójnych zasady nazewnictwa... 3 III. Zasady nazewnictwa wybrane zagadnienia Język oraz forma nazewnictwa Skróty językowe Czytelność zapisu... 4 a) Elementy (węzły)... 4 b) Atrybuty Kodowanie znaków Grupowanie elementów Przestrzeń nazw... 5 IV. Zasady Nazewnictwa - Reguły... 6 Strona 2 z 9

3 I. Wstęp Dokument został opracowany w ramach projektu e-puap. Niniejszy materiał stanowi założenia inicjujące proces ustanowienia rekomendacji Interoperacyjności w obszarze dokumentów elektronicznych. Celem dokumentu jest ustanowienie rekomendacji głównych zasad związanych z tworzeniem dokumentów elektronicznych w strukturze. Zawarte w dokumencie zalecenia maja ułatwić prace nad tworzeniem wzorów oraz samych dokumentów elektronicznych. Dokument powstał w oparciu o: Doświadczenia zebrane podczas prac prowadzonych w administracji publicznej. Wymagania polskiego prawa Przegląd doświadczeń międzynarodowych II. Znaczenie spójnych zasady nazewnictwa Proces tworzenia i zarządzania Interoperacyjnością (opisany w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów ) wymaga stosowania spójnego i znormalizowanego sposobu nazewnictwa. Zastosowanie jednolitego standardu nazywania elementów struktury i ułatwi proces re-używalności oraz zapewni spójne zasady zarządzania schematami dziedzinowymi. Zestandaryzowane nazewnictwo oraz stosowanie reguł ułatwia interpretację dokumentów elektronicznych (systemy informatyczne wiedzą czego mogą się spodziewać w zawartości dokumentu elektronicznego). III. Zasady nazewnictwa wybrane zagadnienia 1. Język oraz forma nazewnictwa Należy dążyć do tego aby elementy, atrybuty i typy były pisane w języku polskim. Nie używać w elementach opisujących strukturę dokumentu znaków diakrytycznych. Należy dążyć do stosowania rzeczowników. <Budynek>123</Budynek> <Wlasciciel>Zenon Kowalski</Wlasciciel> <Building>123</Building> <Właściciel>Zenon Kowalski</Właściciel> 2. Skróty językowe Należy unikać tworzenia skrótów. Strona 3 z 9

4 <NumerKatalogowy>12324</NumerKatalogowy> <Adresat rodzaj="osoba fizyczna">jan Nowak</Adresat> <NrKat>12323</NrKat> <Adresat rodz="osoba fizyczna">jan Nowak</Adresat> 3. Czytelność zapisu a) Elementy (węzły) Dla elementów zaleca się używać notację UpperCamelCase. <Nazwisko>Nowak</Nazwisko> <PodstawaPrawna>(Dz.U. z 2000 r. Nr 98)</PodstawaPrawna> <UzasadnienieFaktycznePrawne> </UzasadnienieFaktycznePrawne> <nazwisko>kowalski</nazwisko> <nazwiskointeresanta>nowak</nazwiskointeresanta> <Podstawa_Prawna>(Dz.U. z 2000 r. Nr 98.)</Podstawa_Prawna> <Uzasadnienie-Faktyczne-Prawne> </Uzasadnienie-Faktyczne-Prawne> b) Atrybuty Dla atrybutów zaleca się używać notację lowercamelcase. <Data typ="utworzenia"> </data> <Nadawca rodzajpodmiotu="instytucja">mswia</nadawca> <Data Typ="utworzenia"> </Data> <Data typ="utworzenia"> </data> <Nadawca rodzajpodmiotu="instytucja">mswia</nadawca> 4. Kodowanie znaków Należy stosować kodowanie w standardzie UTF-8. (Rozporządzenie Rady Ministrów z dnia 11 października 2005 r. w sprawie minimalnych wymagań dla systemów teleinformatycznych Dz.U nr 212 poz ). Informacje o kodowaniu należy w odpowiedni sposób zapisać. <?xml version="1.0" encoding="utf-8"?> <?xml version="1.0"?> Strona 4 z 9

5 <?xml version="1.0" encoding="iso "?> <?xml version="1.0" encoding="windows-1250"?> 5. Grupowanie elementów Należy dążyć, do grupowania elementów tego samego rodzaju. <Data/> <Zalaczniki> <Zalacznik typ="dokumentxml">wniosek1.xml</zalacznik> <Zalacznik typ="dokumentxml">wniosek2.xml</zalacznik> <Zalacznik typ="arkuszcss">wniosek.css</zalacznik> </Zalaczniki> <Data/> <Zalacznik typ="dokumentxml">wniosek1.xml</zalacznik> <Zalacznik typ="dokumentxml">wniosek2.xml</zalacznik> <Zalacznik typ="arkuszcss">wniosek.css</zalacznik> 6. Przestrzeń nazw Zaleca się aby główny element dokumentu posiadał domyślną przestrzeń nazw bez prefiksu. <GlownyElementDokumentu xmlns=" </GlownyElementDokumentu> <GlownyElementDokumentu>... </GlownyElementDokumentu> <umg:glownyelementdokumentu xmlns:umg=" </umg:glownyelementdokumentu> Strona 5 z 9

6 IV. Zasady Nazewnictwa - Reguły A. Wymagania Ogólne Rodzaj ID Nazwa Rekomendacja Reguła Ogólne A.1 Wybór języka schematu Wymaga się, aby schematy były definiowane zgodnie z zaleceniami W3C Schema: Schema Part 1: Structures i Schema Part 2: Datatypes z 2 maja Ogólne A.2 Wersja Wymaga się, aby wszystkie schematy były zgodne z wersją 1.0 zaleceń W3C z 16 sierpnia 2006: Extensible Markup Language () 1.0 (Czwarta edycja). Ogólne A.3 Wybór schematu kodowania Wymaga się, aby wszystkie schematy stosowały UTF-8 jako schemat kodowania B. Wymagania dla dokumentów Rodzaj ID Nazwa Rekomendacja Reguła B.1 Nazwy zastrzeżone Na poziomie głównym dokumentu zaleca się umieszczanie tylko dwóch węzłów: OpisDokumentu oraz DaneDokumentu. Definicja zawartości tych węzłów (atrybutów, podwęzłów) jest zawarta w dokumencie P6. MetaWzór Dokumentu Elektronicznego czyli jak budować schemy B.2 Hierarchia węzłów Hierarchia węzłów i podwęzłów powinna być zgodna z faktycznymi relacjami pomiędzy obiektami. B.3 Grupowanie tych samych typów W przypadku występowania na jednym poziomie tych samych typów zaleca się ich grupowanie. B.4 Atrybut ID Zaleca się umieszczanie w każdym węźle dokumentu atrybut ID B.5 Nazewnictwo w języku polskim Zaleca się, aby elementy, atrybuty i typy były nazywane w języku polskim i pisane bez użycia polskich znaków diakrytycznych. Dopuszcza się stosowanie nazw w innych językach w wyjątkowych przypadkach, gdy nazwa przetłumaczona na język polski będzie niezrozumiała. Strona 6 z 9

7 B.6 Liczba pojedyncza rzeczowników Wymaga się, aby rzeczownik stanowiący część elementu, atrybutu lub typu występował w liczbie pojedynczej chyba, że istnieje wyłącznie jego liczba mnoga. B.7 Użycie UpperCamelCase Wymaga się, aby element były nazywane przy użyciu UpperCamelCase. B.8 Użycie lowercamelcase Wymaga się, aby atrybuty były nazywane zgodnie z lowercamelcase. B.9 Skróty i skrótowce Zaleca się, aby skróty i skrótowce nie były używane w nazwach. Dopuszcza się stosowanie skrótów powszechnie znanych na przykład: np., lp., nr, etc. Zaleca się wyjaśnienie skrótów w komentarzach umieszczonych w schemacie. B.10 Unikanie spójników Wymaga się, aby nazwy były konstruowane przy pomocy czasowników, rzeczowników i przymiotników. B.11 Użycie znaków w nazwach W nazwach nie należy stosować znaków podkreślenia (_), kropki (.), ani myślnika (-). C. Wymagania dla Schematów () Rodzaj ID Nazwa Rekomendacja Reguła C.1 Klasy komponentów Zasady tworzenia i zarządzania klasami komponentów są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów C.2 Wielokrotne stosowanie istniejących elementów i typów Zaleca się wielokrotne stosowanie elementów lub typów należących do wcześniej zdefiniowanych klas komponentów. C.3 Umieszczanie zdefiniowanych schematów Wszystkie zdefiniowane schematy muszą być umieszczone w repozytorium Interoperacyjności. C.4 Przypisanie przestrzeni nazw Wymaga się, aby wszystkie schematy miały przypisaną przestrzeń nazw. C.5 Stosowanie include i import Konstrukcję include należy stosować tylko wtedy, jeżeli wskazuje na moduł schematu w tej samej przestrzeni nazw. W przeciwnym przypadku należy stosować konstrukcję import. Strona 7 z 9

8 C.6 Stosowanie schemalocation Wszystkie atrybuty schemalocation powinny być określone za pomocą absolutnego i ważnego URL a, który określa lokalizację wskazywanego modułu schematu w repozytorium Interoperacyjności. C.7 Typ przyrostka Wymaga się, aby nazwa typu prostego i złożonego kończyła się przyrostkiem Typ. C.8 Powiązanie pomiędzy nazwami elementów i typów Zaleca się, aby element miał tą samą nazwę jak jego typ z pominiętym przyrostkiem Typ. C.9 Nazywanie plików zawierających schematy Zasady nazywania plików są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów C.10 Powielanie istniejących typów Nowe typy proste i złożone nie mogą być identycznie zdefiniowane jak już istniejące. Powinno się unikać tworzenia nowych typów tylko przez zmianę nazwy już istniejących. C.11 Globalne definicje typów Zaleca się, aby typy proste i złożone były zdefiniowane globalnie. Umożliwi to ich reużywalność C.12 Reprezentacja list kodowych Zaleca się, aby listy kodowe były określane przy użyciu konstrukcji enumeration. C.13 Wartości w wyliczeniach Zaleca się, aby wartość konstrukcji enumeration była określona przy pomocy małych liter. C.14 Przestrzenie nazw dla elementów Wymaga się, aby wszystkim elementom przypisana była przestrzeń nazw, czyli atrybut elementformdefault w głównym elemencie schematu powinien mieć przypisaną wartość qualified, a atrybut form nie może być stosowany w deklaracjach elementu. C.15 Przestrzeń nazw dla atrybutów Nie należy przypisywać żadnemu atrybutów przestrzeni nazw, czyli atrybut attributeformdefault w głównym elemencie schematu powinien mieć przypisaną wartość unqualified, a atrybut form nie może być stosowany w deklaracjach atrybutu. C.16 Wersjonowanie przestrzeni nazw Zasady wersjonowania przestrzeni nazw są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów C.17 Stosowanie wersji Dopuszcza się stosowanie atrybutu version w głównym elemencie schematu w celach wewnętrznych. Strona 8 z 9

9 C.18 Reprezentacja przestrzeni nazw Wymaganie Wymaga się, aby przestrzeń nazw reprezentowała obowiązujący URL w repozytorium Interoperacyjności i była zgodna z obowiązującym wzorcem zdefiniowanym w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów C.19 Dokumentacja schematów Zasady dokumentowanie schematów są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów C.20 Dokumentacja modułów schematów Zasady dokumentowania modułów schematów są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów C.21 Dokumentacja typów, elementów i atrybutów Zasady dokumentowania typów, elementów i atrybutów są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów Strona 9 z 9