MINISTERSTWO SPRAW WEWNĘTRZNYCH I ADMINISTRACJI DEPARTAMENT INFORMATYZACJI

Transkrypt

1 MINISTERSTWO SPRAW WEWNĘTRZNYCH I ADMINISTRACJI DEPARTAMENT INFORMATYZACJI ul. Wspólna 1/ Warszawa ZASADY NAZEWNICTWA DOKUMENTÓW XML Projekt współfinansowany Przez Unię Europejską Europejski Fundusz Rozwoju Regionalnego

2 Autor Zespół projektowy Klient Ministerstwo Spraw Wewnętrznych i Administracji Wersja dokumentu 2.01 Liczba stron 11 Historia zmian Wersja Data Kto Opis zmian Zespół projektowy epuap Zespół projektowy epuap Zespół projektowy epuap Utworzenie dokumentu Modyfikacja dokumentu (zmiany wypracowane w ramach publicznej dyskusji na portalu epuap oraz w trakcie warsztatów) Uzupełnienie dokumentu 2/11

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

4 Wstęp 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 XML. 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świadczeo 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 XML) wymaga stosowania spójnego i znormalizowanego sposobu nazewnictwa. Zastosowanie jednolitego standardu nazywania elementów struktury XML i XSD 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ążyd do tego aby elementy, atrybuty i typy były pisane w języku polskim. Nie używad w elementach opisujących strukturę dokumentu znaków diakrytycznych. Należy dążyd do stosowania rzeczowników. <Budynek>123</Budynek> <Wlasciciel>... </Wlasciciel> <Building>123</Building> <Właściciel>... </Właściciel> 4/11

5 Zasady nazewnictwa wybrane zagadnienia 2. Skróty językowe Należy unikać tworzenia skrótów. <NumerKatalogowy>12324</NumerKatalogowy> <Adresat rodzaj="osobafizyczna">... </Adresat> <NrKat>12323</NrKat> <Adresat rodz="osobafizyczna">... </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> 5/11

6 Zasady nazewnictwa wybrane zagadnienia 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"?> <?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> 6/11

7 Zasady nazewnictwa wybrane zagadnienia Niezalecane: <umg:glownyelementdokumentu xmlns:umg=" </umg:glownyelementdokumentu> <GlownyElementDokumentu>... </GlownyElementDokumentu> 7/11

8 Zasady Nazewnictwa Reguły IV. Zasady Nazewnictwa Reguły Definicja rekomendacji: zasady oznaczone tym atrybutem muszą być bezwzględnie spełnione. Niespełnienie chociaż jednej z zasad oznacza, że weryfikowany obiekt jest niezgodny z zasadami opisanym w niniejszym dokumencie zasady oznaczone tym atrybutem nie muszą być spełnione ale zaleca się aby były. Niespełnienie nawet wszystkich zasad z atrybutem nie wpływa na wynik weryfikacji z zasadami opisanym w niniejszym dokumencie. Dokumnety referencyjne: 1. MetaWzór Dokumentu Elektronicznego czyli jak budować schematy XML 2. Zasady Zarządzania Interoperacyjnością Dokumentów XML 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 XML Schema: XML Schema Part 1: Structures i XML Schema Part 2: Datatypes z 2 maja Ogólne A.2 Wersja XML Wymaga się, aby wszystkie schematy XML były zgodne z wersją 1.0 zaleceń W3C XML z 16 sierpnia 2006: Extensible Markup Language (XML) 1.0 (Czwarta edycja). Ogólne A.3 Wybór schematu kodowania XML B. Wymagania dla dokumentów XML Rodzaj ID Nazwa Rekomendacja Reguła Wymaga się, aby wszystkie schematy XML stosowały UTF-8 jako schemat kodowania XML XML B.1 Nazwy zastrzeżone Jako główny węzeł wymaga się zastosowanie elementu Dokument. Na kolejnym poziomie dokumentu XML wymaga się umieszczanie tylko węzłów: OpisDokumentu, DaneDokumentu TrescDokumentu InnyObiekt. Definicja zawartości tych węzłów (atrybutów, podwęzłów) jest zawarta w dokumencie MetaWzór Dokumentu Elektronicznego czyli jak budować schematy XML 8/11

9 Zasady Nazewnictwa Reguły XML B.2 Hierarchia węzłów Hierarchia węzłów i podwęzłów powinna być zgodna z faktycznymi relacjami pomiędzy obiektami. XML B.3 Grupowanie tych samych typów W przypadku występowania na jednym poziomie tych samych typów zaleca się ich grupowanie. XML B.4 Atrybut ID Zaleca się umieszczanie w każdym węźle dokumentu atrybut ID XML B.5 Nazewnictwo w języku polskim XML B.6 Liczba pojedyncza rzeczowników XML B.7 Użycie UpperCamelCase XML B.8 Użycie lowercamelcase 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. Wymaga się, aby rzeczownik stanowiący część elementu, atrybutu lub typu występował w liczbie pojedynczej chyba, że istnieje wyłącznie jego liczba mnoga. Wymaga się, aby element były nazywane przy użyciu UpperCamelCase. Wymaga się, aby atrybuty były nazywane zgodnie z lowercamelcase. XML B.9 Skróty i skrótowce Zaleca się, aby skróty i skrótowce nie były używane w nazwach. XML B.10 Unikanie spójników XML B.11 Użycie znaków 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 XSD. Zaleca się, aby nazwy były konstruowane przy pomocy czasowników, rzeczowników i przymiotników. Niezaleca się stosowania konstrukcji typu <BudynekOrazLokal/> lub <MiejscowoscIKod/> C. Wymagania dla Schematów XML (XSD) Rodzaj ID Nazwa Rekomendacja Reguła XSD C.1 Klasy komponentów W nazwach nie należy stosować znaków podkreślenia (_), kropki (.), ani myślnika (-). Zasady tworzenia i zarządzania klasami komponentów są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów XML 9/11

10 Zasady Nazewnictwa Reguły XSD C.2 Wielokrotne stosowanie istniejących elementów i typów XSD C.3 Umieszczanie zdefiniowanych schematów XSD C.4 Przypisanie przestrzeni nazw XSD C.5 Stosowanie include i import XSD C.6 Stosowanie schemalocation Zaleca się wielokrotne stosowanie elementów lub typów należących do wcześniej zdefiniowanych klas komponentów. Zaleca się aby wszystkie zdefiniowane schematy XML były umieszczone w repozytorium Interoperacyjności. Wymaga się, aby wszystkie schematy XML miały przypisaną przestrzeń nazw. Zasady przypisywania przestrzeni nazw są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów XML 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. 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. XSD C.7 Typ przyrostka Wymaga się, aby nazwa typu prostego i złożonego kończyła się przyrostkiem Typ. Np. OsobaTyp, PodmiotTyp XSD C.8 Powiązanie pomiędzy nazwami elementów i typów XSD C.9 Nazywanie plików zawierających schematy XML XSD C.10 Powielanie istniejących typów XSD C.11 Globalne definicje typów XSD C.12 Reprezentacja list kodowych XSD C.13 Wartości w wyliczeniach XSD C.14 Przestrzenie nazw dla elementów Zaleca się, aby element miał tą samą nazwę jak jego typ z pominiętym przyrostkiem Typ. Dopuszcza się odstępstwa. Zasady nazywania plików są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów XML 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. Zaleca się, aby typy proste i złożone były zdefiniowane globalnie. Umożliwi to ich re-używalność Zaleca się, aby listy kodowe były określane przy użyciu konstrukcji enumeration. Zaleca się, aby wartość konstrukcji enumeration była określona przy pomocy małych liter. Wymaga się, aby wszystkim elementom przypisana była przestrzeń nazw, czyli 10/11

11 Zasady Nazewnictwa Reguły XSD C.15 Przestrzeń nazw dla atrybutów XSD C.16 Wersjonowanie przestrzeni nazw Zalecenie atrybut elementformdefault w głównym elemencie schematu powinien mieć przypisaną wartość qualified, a atrybut form nie może być stosowany w deklaracjach elementu. Nie należy przypisywać żadnemu z 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. Zasady wersjonowania przestrzeni nazw są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów XML XSD C.17 Stosowanie wersji Zalecenie Dopuszcza się stosowanie atrybutu version w głównym elemencie schematu w celach wewnętrznych. XSD C.18 Reprezentacja przestrzeni nazw XSD C.19 Dokumentacja schematów XML XSD C.20 Dokumentacja modułów schematów XSD C.21 Dokumentacja typów, elementów i atrybutów XSD C.22 Udostępnianie schematów XML XSD C.23 Stosowanie wielu importów dla tej samej przestrzeni nazw Wymaganie Wymaga się, aby przestrzeń nazw reprezentowała URL w repozytorium Interoperacyjności (lub innym repozytorium) i była zgodna z obowiązującym wzorcem zdefiniowanym w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów XML. Adres URL musi być dostępny publicznie. Przykład przestrzeni nazw : schematy/pesel2/2006/11/08/ Zalecenie Zasady dokumentowanie schematów XML są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów XML Zalecenie Zasady dokumentowania modułów schematów są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów XML Zasady dokumentowania typów, elementów i atrybutów są zdefiniowane w dokumencie Zasady Zarządzania Interoperacyjnością Dokumentów XML Wymaganie Wymaga się aby wszystkie zdefiniowane schematy były dostępne publicznie. Dostęp do schematów powinien być realizowany na podstawie adresu URL (http lub https) Nie zaleca się stosowania więcej niż jednej konstrukcji import dla tej samej przestrzeni nazw. 11/11