Delimite um fluxo e a unidade de cada registro
Escolha uma troca concreta, como solicitações entre atendimento e área executora. Antes de listar colunas, descreva o que cada linha representa. É uma pessoa, um pedido, uma etapa ou uma tentativa de execução? Sem essa definição, a equipe pode transportar os valores corretamente e ainda contar pessoas como atendimentos ou etapas como solicitações diferentes.
O dicionário deve ter um escopo que caiba numa revisão conjunta. Reúna a área que registra, a equipe que mantém o sistema e quem consome a informação. Uma exportação técnica ajuda a localizar campos, mas não substitui a explicação do processo. A mesma coluna pode ter sido preenchida com interpretações distintas em unidades diferentes ao longo do tempo.
O guia de interoperabilidade no setor público apresenta a importância do significado compartilhado. Aqui, a entrega é mais delimitada: uma referência de campos suficiente para interpretar uma troca específica. Não é necessário iniciar por um catálogo completo de toda a prefeitura para resolver uma ambiguidade que já afeta o serviço.
Separe o nome técnico da definição de negócio
Para cada campo, registre nome técnico, rótulo usado no processo e definição compreensível. Situação não deve ser explicada apenas como situação do pedido. Indique quais acontecimentos o campo representa, quem pode alterá-lo e como se relaciona com outras datas. Se não houver uma definição aceita, marque a dúvida e encaminhe a decisão antes de ampliar o consumo.
Em um exemplo hipotético, um sistema usa concluído para indicar fim da análise documental, enquanto outro usa o mesmo termo para entrega do serviço ao cidadão. Traduzir ambos para um único código apagaria uma diferença essencial. O dicionário precisa preservar os dois conceitos ou registrar uma regra de transformação aprovada, com limites reconhecidos por quem utiliza o resultado.
A página de dados abertos do MIDR apresenta o dicionário como relação de nomes, atributos e definições dos elementos disponibilizados. Esse exemplo ajuda a compreender o papel da documentação, mas cada fluxo municipal precisa de seu próprio conteúdo. Não copie descrições externas para preencher campos cujo uso local ainda não foi confirmado.
Registre formato, unidade e referências de tempo
Documente tipo de informação, tamanho ou precisão relevante e formato de intercâmbio. Para valores, indique unidade, escala e condições de arredondamento. Um número sem unidade pode significar reais, centavos, dias ou minutos. O consumidor não deve inferir essas escolhas olhando apenas alguns registros de exemplo, pois mudanças de faixa podem tornar a suposição invisível até surgir um erro.
Para datas, descreva o evento representado, a precisão e o fuso quando houver horário. Data de criação no sistema não é necessariamente data de recebimento do pedido. Uma carga histórica pode registrar milhares de itens no mesmo dia técnico. Usar essa coluna para medir espera produz uma análise diferente daquela baseada no início real da solicitação.
Quando um campo guardar referência territorial, identifique o cadastro e a versão pertinente. O artigo sobre códigos do IBGE no cruzamento de bases detalha verificações de identidade territorial. O dicionário deve registrar qual código foi usado e não apenas classificá-lo como número, porque o formato técnico não explica a referência administrativa.
Explique códigos, valores ausentes e exceções
Liste os valores permitidos e seus significados. Se um código deixar de ser usado, preserve a informação necessária para interpretar o histórico. Evite reutilizar o mesmo código para um conceito novo sem controle de versão. Uma tabela de domínio deve indicar responsável e situação dos valores, além de sua grafia ou representação técnica.
Diferencie não informado, não se aplica, desconhecido e zero quando forem situações distintas no processo. Não crie uma classificação apenas para deixar a documentação mais completa: confirme o que a origem realmente registra. Se o sistema mistura esses casos, descreva a limitação e seus efeitos. O consumidor precisa saber quando uma comparação ou cálculo fica comprometido.
Exemplos fictícios ajudam a demonstrar o tratamento de cada caso. Para um campo de quantidade, zero pode representar ausência confirmada, enquanto vazio representa falta de medição. Se o destino converte ambos para zero, a integração altera o significado. A regra de transformação deve ser explicitada e avaliada antes de usar o conjunto em indicadores ou decisões.
Documente origem e transformação sem expor dados reais
Informe de onde o campo vem, como é produzido e quem pode esclarecer divergências. Se o valor for calculado, registre entradas, regra e momento de cálculo. Um total recebido de outro sistema não se torna uma medida independente apenas porque passou por uma nova tabela. Preservar a linhagem evita comparar cópias da mesma informação como se fossem confirmações separadas.
Inclua exemplos sintéticos que reproduzam formatos e exceções, sem transportar dados pessoais de produção para o documento de referência. O dicionário pode descrever campos restritos sem oferecer acesso ao conteúdo desses campos. A documentação e a autorização de consulta são decisões diferentes; conhecer a estrutura não permite extrair uma base inteira para facilitar o desenvolvimento.
Nos requisitos técnicos publicados pelo Conecta gov.br, o dicionário aparece junto à documentação de APIs e aos exemplos de homologação. Isso ilustra uma combinação útil: explicar significado e permitir ensaiar o consumo. Não se deve concluir que uma integração municipal está habilitada ao programa por produzir esses documentos; acesso e condições seguem os procedimentos próprios.
Valide o dicionário com quem vai consumir a troca
Escolha casos representativos e peça que o consumidor os interprete usando apenas a documentação. Depois compare com o sentido confirmado pela área produtora. Essa revisão deve incluir um caso comum, uma ausência e uma mudança de estado. Se a interpretação depender de explicação informal não registrada, acrescente a informação pertinente ao dicionário e repita o exercício.
Para campos que alimentam cálculo, execute uma conferência pequena com resultado conhecido. Por exemplo, veja se o total de solicitações considera pedidos cancelados conforme a definição aprovada. A documentação pode estar clara e a consulta usar uma regra antiga. Por isso, a verificação precisa alcançar o uso real no relatório ou integração, e não apenas o texto da ficha.
O guia de qualidade dos indicadores municipais complementa a leitura de cobertura e comparabilidade. O dicionário fornece os conceitos de base, mas não resolve sozinho a qualidade do preenchimento. Registre divergências entre definição e dados observados para que a área responsável escolha correção, restrição de uso ou explicação da limitação.
Versione mudanças que alteram a interpretação
Uma mudança de significado pode ocorrer mesmo sem renomear a coluna. Alterar o marco de conclusão, a unidade ou a regra de um código afeta consumidores e séries históricas. Registre versão, início de aplicação, motivo e impacto. A equipe precisa saber quais registros seguem a definição anterior e como serão tratados em comparações que atravessam a mudança.
Antes de alterar o fluxo, identifique relatórios, integrações e rotinas que utilizam o campo. Avise os responsáveis pelo procedimento institucional e confirme adaptações necessárias. Não esconda uma ruptura com conversão silenciosa. Se for possível manter compatibilidade, explique a regra; se não for, planeje a transição e deixe os limites visíveis para quem decide com os dados.
Preserve as versões necessárias para reconstruir análises passadas. Uma documentação sempre sobrescrita deixa o histórico sem referência. Ao corrigir uma definição equivocada, diferencie correção do texto de alteração efetiva no sistema. A data de atualização do documento, isoladamente, não prova quando os registros passaram a ser produzidos conforme a regra nova.
Mantenha uma referência que ajude a decidir
Comece com os campos críticos do fluxo escolhido e publique a referência no ambiente institucional autorizado. Atribua responsável por dúvidas e atualização. Evite multiplicar planilhas com versões concorrentes entre áreas. Uma referência simples, reconhecida e próxima da rotina tem mais chance de ser usada do que um catálogo extenso cujo conteúdo ninguém confirma.
A página de dados, integração e automação apresenta o posicionamento do Grupo Edge sobre conectar informação ao processo. Este roteiro não atribui ao grupo uma ferramenta de catálogo pronta ou integração específica. O foco é produzir um acordo verificável de significado que possa orientar tecnologia, operação e análise.
Uma primeira versão útil permite responder o que cada linha representa, o que um campo significa, quais valores aceita, como tratar ausências e a quem recorrer quando a definição mudar. Confira essas respostas com um uso concreto. A conclusão do trabalho depende dessa capacidade de interpretação compartilhada, e não da quantidade de colunas preenchidas na documentação.
Perguntas frequentes
O esquema técnico de uma tabela substitui o dicionário?
Ele informa estrutura, mas pode não explicar significado, unidade, códigos e condições de uso. Esses elementos precisam ser confirmados com a área responsável.
Mudar apenas a descrição pode afetar os relatórios?
Se a descrição revela uma interpretação antes equivocada ou acompanha mudança de regra, os consumidores precisam ser revistos. Diferencie correção documental de alteração dos dados.